perfr

Profile a running program with no code change. The Rust service runs on Linux, macOS and Windows. The viewer is a web page, so any browser on any device can open it.

perfr, formerly Orbit, is a Rust re-implementation of Orbit by its original author. The capture service (perfr) and the browser viewer are the Rust work. The original C++ application is not in this tree; crates/README.md says where its history is.

Both systems attach to a process that is already running. Both can hook functions with Frida, and both take manual scopes from Rust, C, C++, and Python. This tree also has bindings for C#, Lua, Zig, Swift, Java, Kotlin, Julia, and Mojo, exercised on Linux against libperfr, and a note on why there is no GDScript extension. A loaded capture in the viewer is capped at a 2 GiB heap. What else each system records is in the table below.

Quick start

curl -fsSL https://perfr.dev/install.sh | sh
perfr
# http://127.0.0.1:44766/

The installer downloads the release for this machine, Linux x86-64 or macOS universal, from perfr.dev, which serves the latest GitHub Release tagged perfr-vX.Y.Z. Until that tag exists, the script stops and says so. The v1.* and nightly-* releases are the legacy C++ build and are not what this installs.

Windows, in PowerShell:

irm https://perfr.dev/install.ps1 | iex
perfr
# http://127.0.0.1:44766/

The same release carries perfr-windows-x86_64.zip. Start perfr from a prompt opened with Run as administrator to record the scheduler, thread states and call stacks (the kernel logger is administrators-only); manual scopes and function hooks need no privilege.

perfr.h is installed to ~/.local/include (the sibling include of PERFR_INSTALL_DIR when that is set). On Windows it is <install dir>\include\perfr.h. Compile C and C++ with -I~/.local/include. The header still loads libperfr from beside perfr on PATH.

perfr update replaces that install. It downloads the latest perfr-v* release, checks the SHA-256, and writes the new files over this one, including perfr.h. A current install prints perfr 0.1.2 is up to date. A replacement prints updated perfr 0.1.1 -> 0.1.2 in ~/.local/bin and restart any running perfr to use the new version. Linux, macOS, and Windows use the same command. On Windows the directory in that line is the install folder, and perfr.h goes to <install>\include.

perfr update --check only prints current, latest, and status. It exits 0 when this install is current or newer than the release, and 1 when an update is available, so a script can tell them apart. Any other failure exits 2. --yes is still accepted and does nothing. cargo, Homebrew, and pip installs are left in place; the command to upgrade them is printed instead.

pip install perfr is the same service in a wheel, including the Frida files. Wheels are built on the same tags and are not on PyPI yet.

Privileges, capture files, and the manual API: docs/manual/index.md.

Function hooks need perfr-hook and libperfr in the same directory as perfr (or PERFR_HOOK / PERFR_LIB); on Windows the files are perfr-hook.exe and libperfr.dll. libperfr is also the library programs load for manual instrumentation. The release archive and the installer put them there. Without them, starting a capture with hooks fails the Frida setup; it does not switch engines on its own. On Linux the kernel engine is a separate choice and needs root or CAP_SYS_ADMIN. It is not in the macOS or Windows builds.

With no arguments, perfr listens on 127.0.0.1:44766.

Drive it from an agent

perfr mcp is a Model Context Protocol server. It lists processes, attaches, searches functions, arms Frida hooks, starts and stops captures, and reads sampling hotspots, call stacks, and per-function timing. It does not edit source. The service has to be running first. The HTTP API has no authentication; keep it on 127.0.0.1.

Claude Code (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "perfr": {
      "command": "perfr",
      "args": ["mcp", "--url", "http://127.0.0.1:44766"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "perfr": {
      "command": "perfr",
      "args": ["mcp", "--url", "http://127.0.0.1:44766"]
    }
  }
}

Streamable HTTP, loopback only:

perfr mcp --http 127.0.0.1:44767 --url http://127.0.0.1:44766

{
  "mcpServers": {
    "perfr": { "url": "http://127.0.0.1:44767/mcp" }
  }
}

Sampling and the scheduler need an elevated prompt on Windows and are not in the macOS build, where the same tools say supported: false and still hook functions. The tool list and the limits are in docs/manual/mcp.md.

Several machines

One viewer can show the processes of several machines on one timeline. The service whose page you open is the hub; on every other machine start the service with --join <hub-host>:44766 (or, from the hub, --connect host,...). The side that is dialed runs with --host 0.0.0.0; without it a service listens on its own machine only. The hub measures each link's clock offset with round-trip probes and moves every remote event onto its own clock; the remotes' processes appear in the hub's list as name @host, and Record on the hub records everywhere. docs/manual/machines.md has the details and the limits.

This is the beginning of the README. Read the rest at the original. Read the full README ↗