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

Every failure renders as {"error": {"code": …, "message": …}} with a real status code — 400 validation, 403 permission, 404 missing, 409 wrong server state, 413 too large, 502 agent transport. The schema is published at /api/openapi.json.

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/, and never a bare cycles. The names the agent's start response lists are the ones it asked for, so on that hardware they are not the keys the data arrives under: read the real names from the SSE data_version stamp's event_types. The server will resolve a bare name onto the per-cluster ones when that is unambiguous, and name the candidates when it is not.

MCP server

perflens mcp serves profiling data to LLM agents over the Model Context Protocol, so an agent can answer “why is this slow” against real perf data and drive a live run on a device. It is a client of the HTTP API above, so a perflens serve must be running. The SDK is an optional dependency:

pip install 'perflens[mcp]'          # or: uv tool install 'perflens[mcp]'
claude mcp add perflens -- perflens mcp

Nineteen tools. Analysis (read-only): perflens_status, perflens_list_sessions, perflens_hot_functions, perflens_hot_stacks, perflens_perf_stat, perflens_list_source_files, perflens_source_hotlines, perflens_compare, perflens_threads, perflens_thread_detail, perflens_device_metrics, perflens_metrics_history. Device control: perflens_agent_info, perflens_agent_connect, perflens_list_processes, perflens_start_profiling, perflens_stop_profiling, perflens_collection_pause. Plus perflens_export, which writes collapsed stacks / JSON / SVG to a file.

Profiles are large — a single event’s snapshot runs from kilobytes to megabytes — so every tool returns a ranked, capped view and tells the agent exactly how to page for more. Config mutation, session deletion and the file browser are deliberately not exposed. The companion skill at skills/perflens-profiling/ teaches the profiling method the tools support; install it with cp -r skills/perflens-profiling ~/.claude/skills/.

Building release packages

./build_package.sh              # server wheel/sdist + native C agent
./build_package.sh --server     # Python wheel + sdist only
./build_package.sh --agent-c    # C agent only (native static binary)

Outputs land in dist/:

dist/
├── perflens-<ver>-py3-none-any.whl     # server (uvx / pipx / pip)
├── perflens-<ver>.tar.gz               # server sdist
├── perflens-agent-c-<ver>.tar.gz       # agent tarball
└── perflens-agent-linux-<arch>         # agent raw binary (stable name)

CI

.github/workflows/test.yml runs the pytest suite on Python 3.10–3.13 (parser, aggregator differentials against device-captured fixtures, source mapper, HTTP API, MCP tools, provisioning against a fake release server, and the C-agent wire protocol driven through a fake framing server with a perf shim), plus a frontend job: OpenAPI schema drift check, vitest unit tests, and a self-contained Playwright browser E2E that replays a fixture session through the real UI.

.github/workflows/build.yml lints (ruff), runs the tests, builds and smoke-runs the Python wheel, builds the static C agent for five architectures (x86_64, aarch64, aarch64_be, armv7, armeb), and builds static addr2line/readelf tools bundles for perflens provision. Big-endian agent targets use musl toolchains from musl.cc since Ubuntu only ships little-endian sysroots. Tagged pushes (v*) create a GitHub Release and attach all artifacts — including raw perflens-agent-linux-<arch> binaries with stable names that install-agent.sh and the agent's --update fetch — and publish the package to PyPI via Trusted Publishing (OIDC, no stored tokens).

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.

Container: one of the two perf record modes fails

Which one depends on the container, so probe rather than assume. Some environments strip the perf capability set: -p <pid> returns empty and a system-wide perf record -a works. An unprivileged LXC container is the opposite case — at perf_event_paranoid=1, per-PID recording works and -a fails outright with “Failure to open any events for recording”. perf_event_paranoid is not namespaced, so it is read-only from inside the container and lowering it requires the host.

Call-graph probing hangs / slow startup

Capability probing tests fp, dwarf, then lbr in sequence — this adds ~10–20 s on a typical target (longer on slow or hybrid-CPU hardware) on first connection. One-time cost; subsequent rounds skip probing.

Project layout

perflens/
├── install-agent.sh              # curl-able agent installer (no sudo)
├── agent-c/
│   ├── src/                      # C agent modules (agent.h + 10 .c files)
│   ├── Makefile                  # native + cross-compile targets
│   └── vendor/zstd/              # vendored zstd amalgamation
├── pyproject.toml                # pip/uv package (console script: perflens)
├── src/perflens/                 # the server package
│   ├── app.py                    # AppContext + lifecycle + main()
│   ├── config.py                 # ServerConfig, CLI parsing, tool probing
│   ├── state.py                  # profiling/metrics state + rebuild worker
│   ├── agentlink.py              # agent TCP wire protocol + session
│   ├── sessions.py               # persistence, replay, perf.data import
│   ├── web.py                    # FastAPI/uvicorn HTTP layer + SSE hub
│   ├── api/                      # Pydantic v2 schemas + response helpers
│   ├── mcp/                      # MCP server (optional [mcp] extra)
│   ├── cli.py                    # serve/import/push-agent/provision/mcp
│   ├── parser.py                 # perf script / perf stat parser
│   ├── aggregator.py             # incremental per-event aggregation
│   ├── source_mapper.py          # addr2line pipeline + path remap
│   ├── symcache.py               # persistent caches (~/.perflens/cache)
│   ├── provision.py              # user-space static-tools download
│   └── ui/                       # built React app (Vite output, ships in the wheel)
├── frontend/                     # React 19 + TypeScript + Vite SPA source
│   ├── src/                      # api client, stores, flamegraph, components
│   ├── e2e/                      # Playwright browser E2E (self-contained)
│   └── openapi.json              # committed schema (CI drift-checked)
├── skills/perflens-profiling/    # agent skill for the MCP server
├── tests/
│   ├── test_*.py                 # pytest (parser, aggregator, HTTP, MCP, agent, ...)
│   ├── fixtures/                 # gzipped perf sessions from real devices
│   ├── sample_workload.c
│   └── Makefile
├── build_package.sh
├── .github/workflows/test.yml    # pytest matrix + vitest + playwright e2e
└── .github/workflows/build.yml   # lint + test + wheel + agents + release