{"id":25854490,"url":"https://github.com/leonhwangprojects/btrace","last_synced_at":"2025-03-01T16:16:29.636Z","repository":{"id":259218035,"uuid":"877337224","full_name":"leonhwangprojects/btrace","owner":"leonhwangprojects","description":"bpflbr is an eBPF enhanced tool to trace some details of bpf prog with LBR. License Apache 2.0","archived":false,"fork":false,"pushed_at":"2025-02-28T15:35:11.000Z","size":1443,"stargazers_count":16,"open_issues_count":6,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-28T20:07:35.286Z","etag":null,"topics":["bpf","bpflbr","ebpf","last-branch-record","lbr"],"latest_commit_sha":null,"homepage":"","language":"C","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/leonhwangprojects.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-23T13:34:52.000Z","updated_at":"2025-02-28T14:36:45.000Z","dependencies_parsed_at":"2024-10-23T16:08:39.441Z","dependency_job_id":"98453a93-9ee6-40e4-89cc-0107a7c65336","html_url":"https://github.com/leonhwangprojects/btrace","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"a1c9637f803e5036cddbe8b8b789b66f705ef37a"},"previous_names":["asphaltt/bpflbr","leonhwangprojects/btrace"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonhwangprojects%2Fbtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonhwangprojects%2Fbtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonhwangprojects%2Fbtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonhwangprojects%2Fbtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonhwangprojects","download_url":"https://codeload.github.com/leonhwangprojects/btrace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241389166,"owners_count":19955107,"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":["bpf","bpflbr","ebpf","last-branch-record","lbr"],"created_at":"2025-03-01T16:16:29.125Z","updated_at":"2025-03-01T16:16:29.626Z","avatar_url":"https://github.com/leonhwangprojects.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n Copyright 2024 Leon Hwang.\n SPDX-License-Identifier: Apache-2.0\n--\u003e\n\n# btrace\n\n`btrace` is a bpf tool to trace kernel functions and bpf progs with Last Branch Records (LBR) on Intel/AMD CPUs.\n\nHere're some references to learn about LBR:\n\n- [An introduction to last branch records](https://lwn.net/Articles/680985/).\n- [Advanced usage of last branch records](https://lwn.net/Articles/680996/).\n- [How to configure LBR (Last Branch Record) on Intel CPUs](https://sorami-chi.hateblo.jp/entry/2017/12/17/230000).\n- [Intel® 64 and IA-32 Architectures Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html).\n\n## btrace output example\n\nThe colorful output of `./btrace -v -k ip_rcv --output-lbr`:\n\n![lbr example](./img/lbr%20stack%20example.png)\n\nThis is a function call stack from callers to callees based on LBR records provided by `bpf_get_branch_snapshot()`, [bpf: Introduce helper bpf_get_branch_snapshot](https://github.com/torvalds/linux/commit/856c02dbce4f).\n\n## Dependencies\n\n- *libcapstone-dev*: for disassembling machine native instructions.\n\n## Build\n\nWith *libcapstone-dev*, build `btrace` by running:\n\n```bash\nmake\n```\n\n## Usage\n\n```bash\n# ./btrace -h\nUsage of btrace:\n  -d, --disasm                disasm bpf prog or kernel function\n  -B, --disasm-bytes uint     disasm bytes of kernel function, 0 to guess it automatically\n      --disasm-intel-syntax   use Intel asm syntax for disasm, ATT asm syntax by default\n      --filter-pid uint32     filter pid for tracing\n  -k, --kfunc strings         filter kernel functions by shell wildcards way\n      --kfunc-all-kmods       filter functions in all kernel modules\n      --limit-events uint     limited number events to output, 0 to output all events\n  -m, --mode string           mode of btrace, exit or entry (default \"exit\")\n  -o, --output string         output file for the result, default is stdout\n      --output-lbr            output LBR perf event\n      --output-stack          output function call stack\n  -p, --prog strings          bpf prog info for btrace in format PROG[,PROG,..], PROG: PROGID[:\u003cprog function name\u003e], PROGID: \u003cprog ID\u003e or 'i/id:\u003cprog ID\u003e' or 'p/pinned:\u003cpinned file\u003e' or 't/tag:\u003cprog tag\u003e' or 'n/name:\u003cprog full name\u003e' or 'pid:\u003cpid\u003e'; all bpf progs will be traced if '*' is specified\n  -v, --verbose               output verbose log\n```\n\n## Feature: dump LBR stack of kernel functions\n\n`btrace` is able to dump LBR stack of kernel functions by `-k` option.\n\n## Feature: dump jited insns of bpf prog\n\n`btrace` is able to dump jited insns of bpf prog with att asm syntax:\n\n```bash\n# bpftool p\n4483: kprobe  name kprobe_skb_3  tag 780473885099d6ae  gpl\n      loaded_at 2024-10-29T14:46:13+0000  uid 0\n      xlated 7544B  jited 3997B  memlock 12288B  map_ids 5449,5446,5447,5451,5450,5448,5444\n      btf_id 6017\n\n# ./btrace -p 4483 --disasm\n; bpf/kprobe_pwru.c:532:0 PWRU_ADD_KPROBE(3)\n0xffffffffc00c0e64: 0f 1f 44 00 00        nopl  (%rax, %rax)\n0xffffffffc00c0e69: 66 90                 nop\n0xffffffffc00c0e6b: 55                    pushq %rbp\n0xffffffffc00c0e6c: 48 89 e5              movq  %rsp, %rbp\n0xffffffffc00c0e6f: 48 81 ec 98 00 00 00  subq  $0x98, %rsp\n...\n\n# echo \"If want to show intel asm syntax\"\n# ./btrace -p 4483 --disasm --disasm-intel-syntax\n; bpf/kprobe_pwru.c:532:0 PWRU_ADD_KPROBE(3)\n0xffffffffc00bde9c: 0f 1f 44 00 00        nop   dword ptr [rax + rax]\n0xffffffffc00bdea1: 66 90                 nop\n0xffffffffc00bdea3: 55                    push  rbp\n0xffffffffc00bdea4: 48 89 e5              mov   rbp, rsp\n0xffffffffc00bdea7: 48 81 ec 98 00 00 00  sub   rsp, 0x98\n...\n```\n\nColorful output (of `./btrace -d -k __netif_receive_skb_core -B 300`) by default:\n\n![disasm example](./img/disasm%20example.png)\n\n## Feature: trace target with fentry\n\nBy default, `btrace` traces targets with fexit. If you want to trace targets with fentry, you can use `--mode entry`.\n\nIt is really useful to trace the details before calling the target function/bpf-prog.\n\n## Feature: dump function stack without LBR\n\nAs `btrace` is able to provide line info for an kernel address, it will provide line info for the addresses of function stack if dbgsym is available.\n\nThe colorful output of `./btrace -v -k ip_rcv --output-stack`:\n\n![func stack example](./img/func%20stack%20example.png)\n\n## Feature: output arguments and return value\n\n`btrace` is able to output type, name and value of arguments, and type and value of return value.\n\n![args and ret example](./img/func%20args%20and%20ret%20example.png)\n\n## Acknowledgments\n\n- [cilium/ebpf](https://github.com/cilium/ebpf) for interacting with bpf subsystem.\n- [daludaluking/addr2line](https://github.com/daludaluking/addr2line) for translating addresses to file and line number by parsing debug info from vmlinux.\n- [knightsc/gapstone](https://github.com/knightsc/gapstone) for disassembling machine native instructions.\n\n## License\n\nThis project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonhwangprojects%2Fbtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonhwangprojects%2Fbtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonhwangprojects%2Fbtrace/lists"}