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.

The UI records one sampling event by default (cycles, or cpu-clock on a target without a PMU); the others are opt-in in the wizard's Perf step and the control bar's settings. Each extra event multiplies the data the device sends.

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), and gates every PR on ruff, mypy and tools/check_version.py. Two more jobs run the protocol tests against the agent built with AddressSanitizer+UBSan and with ThreadSanitizer (make SANITIZE=…) and the C unit tests (make check); a shellcheck job covers the shell scripts. A frontend job adds the OpenAPI schema and TypeScript typegen drift checks, vitest unit tests, a self-contained Playwright browser E2E that replays a fixture session through the real UI, and a smoke run of the docs screenshot harness.

.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. Every agent asset is a musl static build (static glibc cannot resolve names on a foreign device), from toolchains published on the repository's toolchains release; both 32-bit ARM assets are soft-float. CI asserts what each asset claims — statically linked, the float ABI, BE8 for big-endian — strips the release binary and keeps the unstripped one as a CI artifact. 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 checks events in one batched perf stat and one perf record, then tries fp, dwarf and lbr call graphs and the pipe mode — about 11–13 s on the devices measured for 0.12.0, longer on slow single-core targets. It runs once per connection, and the agent answers status (reporting probing) and stop while it runs; the agent log ends it with Probe finished in N s. Switching process only re-checks the new pid.

Project layout

perflens/
├── install-agent.sh              # curl-able agent installer (no sudo)
├── agent-c/
│   ├── src/                      # C agent modules (agent.h + 12 .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