{"id":18258706,"url":"https://github.com/maaarcocr/perb","last_synced_at":"2025-10-13T21:35:30.109Z","repository":{"id":65138399,"uuid":"580126800","full_name":"Maaarcocr/perb","owner":"Maaarcocr","description":"perb allows perf to profile ruby","archived":false,"fork":false,"pushed_at":"2023-01-24T15:33:03.000Z","size":1418,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-20T17:13:35.487Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Maaarcocr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-12-19T19:37:09.000Z","updated_at":"2024-04-08T08:07:47.000Z","dependencies_parsed_at":"2023-02-13T22:46:01.376Z","dependency_job_id":null,"html_url":"https://github.com/Maaarcocr/perb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maaarcocr%2Fperb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maaarcocr%2Fperb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maaarcocr%2Fperb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maaarcocr%2Fperb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Maaarcocr","download_url":"https://codeload.github.com/Maaarcocr/perb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247237681,"owners_count":20906330,"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","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":[],"created_at":"2024-11-05T10:34:02.262Z","updated_at":"2025-10-13T21:35:25.074Z","avatar_url":"https://github.com/Maaarcocr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Perb\n\n`perb` automatically instruments your methods such that they show up when a ruby executable gets profiled with perf. it works by\nwrapping all methods with:\n\n```ruby\nPerb::wrapper(\u003csome_id\u003e) do\n    ... (your method code here)\nend\n```\n\nFor each method it JITs a small assembly function which just yields back to your ruby method. The assembly looks like\nthis:\n\n```assembly\npush rbp\nmov rbp, rsp\nxor rdi, rdi\ncall rb_sys::rb_yield\nleave\nret\n```\n\nThen, we produce a perf map file (as described [here](https://github.com/torvalds/linux/blob/0513e464f9007b70b96740271a948ca5ab6e7dd7/tools/perf/Documentation/jit-interface.txt)) which maps the address of the JITed assembly to the ruby function we are wrapping. This way perf\ncan show ruby function names (and their location in the file system) in its output.\n\nInspired by the work done to do something similar for Python, which is explained [here](https://docs.python.org/zh-cn/dev/howto/perf_profiling.html)\n\n## Installation\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add perb\n\nIf bundler is not being used to manage dependencies, install the gem by executing:\n\n    $ gem install perb\n\n## Usage\n\nIn order for this to work, you need ruby to be compiled with `CFLAGS=\"-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer\"`\nand also all your native extensions to do so as well. For rust you want: `RUSTFLAGS=\"-C force-frame-pointers=yes\"`\n\nWithout this you will see incorrect perf results, as perf won't be able to profile correctly your program.\n\nHaving done this, you can setup `perb` with `require \"perb/setup\"` which should be required before all the code that you\nwant to be able to profile. See `bin/perf_test` as an example. Then you can just:\n\n```shell\nperf record -g \u003cyour-ruby-executable\u003e\n```\n\nand you should be able to profile native and ruby code with one profiler (perf).\n\n## Caveats\n\nI've noticed that perf drops stack frames when the stack gets really deep, which results in weird results. Given that\nthe call graphs that we are recording are fairly convoluted (they also include all the internals of the Ruby VM) this\ncan happen quite quickly. You should be able to increase such limit with:\n\n```\nsudo sysctl kernel.perf_event_max_stack=\u003cstack-size\u003e\n```\n\nThis currently will break anything that patches `load_iseq` like `bootsnap`.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/Maaarcocr/perb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/Maaarcocr/perb/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Perb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Maaarcocr/perb/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaaarcocr%2Fperb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaaarcocr%2Fperb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaaarcocr%2Fperb/lists"}