{"id":16908838,"url":"https://github.com/kakkoyun/py-perf","last_synced_at":"2026-03-08T10:36:37.606Z","repository":{"id":198495961,"uuid":"668718092","full_name":"kakkoyun/py-perf","owner":"kakkoyun","description":"A Proof-of-concept, low-overhead, sampling CPU profiler for Python implemented using eBPF.","archived":false,"fork":false,"pushed_at":"2023-10-05T15:13:40.000Z","size":780,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-30T18:04:03.523Z","etag":null,"topics":["bpf","ebpf","ebpf-programs","optimization","perfomance","performance-testing","profiler","python","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kakkoyun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-20T12:45:47.000Z","updated_at":"2025-06-04T14:53:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"e608df27-0d6f-4fce-ae4e-ff91dd34d6d8","html_url":"https://github.com/kakkoyun/py-perf","commit_stats":null,"previous_names":["kakkoyun/py-perf"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kakkoyun/py-perf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kakkoyun%2Fpy-perf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kakkoyun%2Fpy-perf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kakkoyun%2Fpy-perf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kakkoyun%2Fpy-perf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kakkoyun","download_url":"https://codeload.github.com/kakkoyun/py-perf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kakkoyun%2Fpy-perf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272885303,"owners_count":25009609,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","ebpf","ebpf-programs","optimization","perfomance","performance-testing","profiler","python","rust"],"created_at":"2024-10-13T18:53:11.878Z","updated_at":"2026-03-08T10:36:37.580Z","avatar_url":"https://github.com/kakkoyun.png","language":"Rust","funding_links":[],"categories":["Python specific"],"sub_categories":[],"readme":"[![wakatime](https://wakatime.com/badge/user/c03c2c3a-0328-4e74-ba79-1ce0eb43a4f8/project/6de0edd3-d3d9-48b1-8f9e-e019fc7b42f1.svg)](https://wakatime.com/badge/user/c03c2c3a-0328-4e74-ba79-1ce0eb43a4f8/project/6de0edd3-d3d9-48b1-8f9e-e019fc7b42f1)\n\n# py-perf\n\nA Proof-of-concept low-overhead sampling CPU profiler written in Rust for Python implemented using eBPF.\nIt is heavily \"influenced\" by [rbperf](https://github.com/javierhonduco/rbperf) and [py-spy](https://github.com/benfred/py-spy).\n\n\u003e [!WARNING]\n\u003e IT IS NOT READY FOR PRODUCTION USE AND IT IS NOT INTENDED TO BE A REPLACEMENT FOR EXISTING TOOLS.\n\u003e It is still considered experimental. Please feel free to contribute or provide feedback!\n\n\u003e [!IMPORTANT]\n\u003e If you are looking for a production-ready tool, please check out [parca-agent](https://github.com/parca-dev/parca-agent) instead.\n\n\u003e [!NOTE]\n\u003e If you are curious how this tool works under the hood, check out the [blog post](https://www.polarsignals.com/blog/posts/2023/10/04/profiling-python-and-ruby-with-ebpf)!\n\n## Features\n\nThe main goals for `py-perf` are:\n\n- On-CPU profiling support\n- Low overhead\n- Profiled processes don't have to be restarted or modified in any way\n\n## Installation\n\nThe latest release is available [here](https://github.com/kakkoyun/py-perf/releases/latest).\n\n## Usage\n\n### CPU sampling\n\n```shell\nsudo py-perf record --pid `pidof python` cpu\n```\n\nSome debug information will be printed, and a flame graph called `py-perf_flame_$date` will be written to disk 🎉\n\n## Supported Python versions\n\nThe currently supported Python (CPython) versions:\n\n- **2.7**: 2.7.x\n- **3.x**: 3.3.x, 3.5.x, 3.6.x, 3.7.x, 3.8.x, 3.9.x, 3.10.x, 3.11.x\n\n## Supported kernels\n\nLinux kernel 4.18 is the minimum required version but 5.x and greater is recommended.\n\n## Building\n\nTo build `py-perf` you would need a modern Linux machine with:\n\n- The Rust toolchain\n- `clang` to compile the BPF code\n- `elfutils` and `zlib` installed\n- `make` and `pkg-config` to build libbpf\n\nOnce the dependencies are installed:\n\n```shell\n# As we are statically linking elfutils and zlib, we have to tell Rustc\n# where are they located. On my Ubuntu system they are under\n$ export RUSTFLAGS='-L /usr/lib/x86_64-linux-gnu'\n$ cargo build [--release]\n```\n\nThe built binary can be found under `target/(debug|release)/py-perf`.\n\n## Developing and troubleshooting\n\nDebug logs can be enabled with `RUST_LOG=debug`. The info subcommand, `py-perf info` shows the supported BPF features as well as other supported details.\n\n## Stability\n\n`py-perf` is in active development and the CLI and APIs might change any time.\n\n## Bugs\n\nIf you encounter any bugs, feel free to open an issue on py-perf's [repo](https://github.com/kakkoyun/py-perf).\n\n## Acknowledgments\n\n`py-perf` wouldn't be possible without all the open-source projects that we benefit from, such as [Rust](https://github.com/rust-lang), [rbperf](https://github.com/javierhonduco/rbperf), [py-spy](https://github.com/benfred/py-spy) and all the superb crates we use in this project, Python, the BPF ecosystem, and many others!\n\n## License\n\nUser-space code: Apache 2\n\nKernel-space code (eBPF profiler): GNU General Public License, version 2\n\n#### TODO\n\n- TODO(kakkoyun): Add sections from parca-agent!\n- TODO(kakkoyun): Add reference to bcc, bcc/granulate and linux/tool examples from facebook.\n\n## Features\n\n- Supports profiling Python processes running in Docker containers. Tested using official Python\n  Docker images (`python:X.Y`).\n- Supports glibc- and musl-based environments.\n- Supports Python compiled in both PIE and non-PIE configurations.\n- Supports Python running standalone and as a library (linked with `libpythonX.Y`).\n\n## Limitations\n\n- Architecture: x86_64.\n- Linux kernel version: oldest version tested is 4.14. Versions 4.11-4.14 may work. Required for\n  `bpf_probe_read_str`.\n- BCC version: using BCC nightly is recommended. v0.17 is known to work.\n- Clang/LLVM: at least version 9.\n\n## Overview\n\nPyPerf uses Linux's perf events subsystem to gather stack samples of running Python interpreters at\na constant interval. Instead of capturing native execution stacks, PyPerf reads the information\nstored by the Python interpreter regarding the current state of execution. Unlike many existing\ntools however, the memory of the process is read from a kernel context. The advantages of this\napproach are mainly reduced system overhead and no intervention with the program being profiled.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkakkoyun%2Fpy-perf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkakkoyun%2Fpy-perf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkakkoyun%2Fpy-perf/lists"}