yandex/perforator: cluster-wide continuous profiling with eBPF

What Perforator solves, and for whom

The README frames Perforator as a continuous profiling app that collects CPU profiles from production without affecting its performance, made by Yandex and inspired by Google-Wide Profiling. That framing sets the audience: teams operating many Linux hosts who want fleet-wide CPU data rather than a single-host sampling session. The README states that Perforator is deployed on tens of thousands of servers in Yandex.

The practical problem is that a one-off profiler tells you what a process did while you watched it. A continuous profiler keeps the data around, so a latency regression reported last Tuesday can be compared against the profile from the week before. Perforator's feature list targets exactly that: scalable storage for profiles and binaries, a query language and UI for inspecting CPU usage through flamegraphs, and stack unwinding that works without frame pointers and without debug symbols on the host. That last point is the one that decides adoption in most shops. If your production binaries are stripped and built with frame-pointer omission, most sampling tools degrade to a shallow stack. Perforator's agent includes an eBPF unwinder specifically to avoid that.

Language coverage is C++, C, Go and Rust, with Java and Python described as experimental. If your fleet is JVM-heavy, treat that word as a boundary rather than a detail.

How the eBPF collector and unwinder fit together

The repository layout separates an agent from the rest of the system. The collector lives under perforator/agent/collector, and its eBPF unwinder program source sits in perforator/agent/collector/progs/unwinder. The README lists that path explicitly as GPL 2.0 licensed code. So the data path starts in the kernel: an eBPF program samples stacks on the host and walks them, which is why the tool can produce useful stacks on stripped binaries without a userspace debug-info lookup on the machine being profiled.

From there the agent ships profiles to a backend that stores both profiles and binaries, and the UI renders them as flamegraphs behind a query language. The README does not document the wire protocol, the storage schema, or the retention model, so anyone evaluating it for a large fleet should read the documentation site rather than infer the architecture from the README. What the README does commit to is the resource envelope: x86 64-bit Linux, 512 MB of RAM with more on very large hosts with many CPUs, and under 1% of host CPUs. Those numbers are the ones to validate against your own hosts, since the README gives no measurement methodology.

One design consequence worth naming: because unwinding happens in the eBPF program, the collector is a kernel-side component with a GPL 2.0 licence, while the rest of the project is Apache-2.0. That split is structural, not cosmetic.

Installing Perforator and running the local record command

The README gives two entry points. For a single machine, including a laptop, it points at the local perforator record CLI command and its native profiling tutorial. For a cluster, it points at a Helm chart for a playground or production Kubernetes deployment. Prebuilt binaries are published on the GitHub releases page, and build-from-source instructions live in the documentation under the build guide.

The README does not inline the exact install commands, so the honest starting point is to fetch a prebuilt binary from the releases page or follow the build guide, then run the record command it documents. The command name below is the one the README uses; the exact flag set lives in the native profiling tutorial at perforator.tech/docs/en/tutorials/native-profiling, so check that page before running anything:

perforator record

That is the local recording entry point named in the README. The README does not print its flags, so the tutorial page is the place to read them.

For a cluster, the README directs you to the Helm chart tutorial under perforator.tech/docs/en/tutorials/kubernetes/helm-chart. The README does not print the chart coordinates or the install command, so take both from that tutorial rather than from this article. What you should end up with is an agent running on each node and a UI you can query for flamegraphs.

Where Perforator is the wrong tool

The feature list is CPU profiles. Nothing in the README describes wall-clock, off-CPU, allocation or memory profiling, so if your regression is a lock contention problem or a leak, Perforator is not the instrument. Sampling profilers also miss short-lived processes that start and exit between sampling intervals, and the README offers no guidance on that class of workload.

The platform constraint is hard: x86 64-bit Linux only. There is no stated support for ARM, and no macOS or Windows collector, even though the README suggests profiling your laptop. That laptop has to be a Linux x86 64 machine. If your production fleet is Graviton or Apple silicon, this project does not cover it today.

Language support is the third boundary. Java and Python are marked experimental, so a polyglot fleet centred on those runtimes should assume partial coverage rather than parity with C++, C, Go and Rust. Finally, the README does not document rollback, upgrade paths between releases, or what happens to stored profiles when the backend schema changes. With releases spaced months apart (v0.0.6 in July 2025, v0.0.7 in November 2025, v0.1.0 in February 2026), that silence matters more than it would for a project shipping weekly. Plan to read the documentation and the release notes before upgrading a production deployment.

Perforator and Parca: two answers to the same question

Parca is the obvious comparison for anyone shopping for eBPF-based continuous profiling, and the difference is in scope rather than in sampling technique. Both collect CPU profiles from Linux hosts with eBPF. Parca is built around a single agent and a server, and is commonly run as a lightweight pair you can stand up quickly. Perforator is described in the README as a cluster-wide app with scalable storage for profiles and binaries, a query language, and a UI, which is a larger commitment: you are deploying a system, not an agent plus a small server.

The second difference is unwinding. Perforator's headline claim is support for unwinding without frame pointers and without debug symbols on the host, implemented in its own eBPF unwinder. If your binaries are already built with frame pointers, that capability buys you less than the deployment cost it carries. If they are not, it is the reason to pick this project over a simpler agent.

The third difference is provenance. Perforator comes out of Yandex and was written for a fleet measured in tens of thousands of servers, which shows in the storage and query components. That is an advantage at scale and overhead at small scale. A team with twenty hosts and frame pointers enabled will find the Helm chart and backend more machinery than the problem requires.

Maintenance, licensing and the upgrade question

The repository's last push was on 2026-09-23, and the latest tagged release is v0.1.0 from 2026-02-24. The gap between the most recent commits and the most recent tag is worth noting: the main branch moves, the releases are less frequent. There is a contributor's guide in CONTRIBUTING.md and two Telegram channels, one Russian and one English, which is where the README points people rather than at a mailing list or issue tracker policy.

On licensing, the README is explicit that the project is Apache-2.0 and that some parts are GPL 2.0. The GPL 2.0 parts are the eBPF program source under perforator/agent/collector/progs/unwinder and portions of the OpenJDK profiling support inside perforator/internal/linguist/jvm. That is a real consideration for anyone who wants to redistribute a modified collector: the kernel-side unwinder carries copyleft terms that the rest of the codebase does not. This is not legal advice, and the exact scope of what counts as a derivative of the eBPF program is a question for your own counsel.

Upgrade cost is the open item. The README does not document a migration procedure between releases, and the release cadence is irregular, so an operator should check the documentation site for version compatibility between the agent and the backend before moving a production cluster from v0.0.7 to v0.1.0.

Editorial conclusion

Adopt Perforator if you run x86 64-bit Linux fleets and need CPU profiles from production without frame pointers or debug symbols on the host; the repository's last push was on 2026-09-23 and the latest release is v0.1.0. Skip it if you need per-thread wall-clock or memory profiling, or you cannot run eBPF. Before committing, verify the GPL 2.0 eBPF unwinder obligations against your distribution model and confirm the Helm chart matches your cluster's storage and query backend.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. yandex/perforator on GitHub