{"id":15294089,"url":"https://github.com/mildsunrise/node_bpfcc","last_synced_at":"2025-04-13T14:11:51.126Z","repository":{"id":42751900,"uuid":"279925864","full_name":"mildsunrise/node_bpfcc","owner":"mildsunrise","description":"🔬 BPF Compiler Collection (BCC) frontend for Node.js","archived":false,"fork":false,"pushed_at":"2023-03-05T06:02:48.000Z","size":392,"stargazers_count":17,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T05:12:48.838Z","etag":null,"topics":["bcc","bpf","kprobes","linux-kernel","nodejs"],"latest_commit_sha":null,"homepage":"","language":"C++","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/mildsunrise.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":"2020-07-15T16:52:20.000Z","updated_at":"2025-01-03T15:24:14.000Z","dependencies_parsed_at":"2023-02-08T04:15:55.205Z","dependency_job_id":"63802afa-33fc-4ca1-ab45-7082b181d885","html_url":"https://github.com/mildsunrise/node_bpfcc","commit_stats":{"total_commits":37,"total_committers":1,"mean_commits":37.0,"dds":0.0,"last_synced_commit":"791520bed95fff1f0c71dd8f2f41e7594f9fa1a9"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fnode_bpfcc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fnode_bpfcc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fnode_bpfcc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fnode_bpfcc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mildsunrise","download_url":"https://codeload.github.com/mildsunrise/node_bpfcc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724629,"owners_count":21151561,"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":["bcc","bpf","kprobes","linux-kernel","nodejs"],"created_at":"2024-09-30T16:57:27.425Z","updated_at":"2025-04-13T14:11:51.107Z","avatar_url":"https://github.com/mildsunrise.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bpfcc\n\nNode.js frontend (aka bindings) for iovisor's [BPF Compiler Collection (BCC)](https://github.com/iovisor/bcc).\n\n**[💡 Examples](./examples)** \u0026nbsp;•\u0026nbsp; **[📚 API reference](https://bpfcc.alba.sh/docs/modules.html)**\n\n\n## Usage\n\n### Installing\n\nFirst you need to [install BCC](https://github.com/iovisor/bcc/blob/master/INSTALL.md) on your system. For modern distros (Ubuntu 20.04+) you can use the repository packages. You don't need to install everything, only the C library \u0026 development files; for instance, on Ubuntu the following should be enough:\n\n~~~ bash\nsudo apt install libbpfcc-dev\n~~~\n\nThen install this module and [`bpf`][], which is required as a peer dependency:\n\n~~~ bash\nnpm install bpfcc bpf\n~~~\n\n### Loading \u0026 attaching programs\n\nTo use it, first pass your program to [`load`][] or [`loadSync`][] to compile it:\n\n~~~ typescript\nconst { loadSync } = require('bpfcc')\n\nconst bpf = loadSync(`\n    #include \u003cuapi/linux/ptrace.h\u003e\n    #include \u003clinux/blkdev.h\u003e\n\n    BPF_HISTOGRAM(dist);\n    BPF_HISTOGRAM(dist_linear);\n\n    int kprobe__blk_account_io_done(struct pt_regs *ctx, struct request *req) {\n        dist.increment(bpf_log2l(req-\u003e__data_len / 1024));\n        dist_linear.increment(req-\u003e__data_len / 1024);\n        return 0;\n    }\n`)\n~~~\n\nThen you need to load \u0026 attach your functions to kernel events using\nthe `attach*` methods:\n\n~~~ typescript\nbpf.attachKprobe('blk_account_io_done', 'kprobe__blk_account_io_done')\n~~~\n\n**Note:** By default, functions starting with prefixes like `kprobe__` are automatically detected and attached, so the above isn't necessary in this case.\n\nAt a later point, if you no longer need it, you can use `bpf.detachAll()` to detach and unload everything from the kernel. If you don't, it might get called by the GC at some point, but it's not recommended to rely on this.\n\n### Accessing maps\n\nOnce tracing has started, we can communicate with our eBPF program by accessing its maps (using the `get*Map` methods). In our case we have two array maps, with uint32 values:\n\n~~~ typescript\nconst dist = bpf.getRawArrayMap('dist')\nconst distLinear = bpf.getRawArrayMap('dist_linear')\n\n// Retrieve current values \u0026 parse them\nconst ys = [...dist].map(x =\u003e x.readUInt32LE(0))\nconsole.log(ys)\n~~~\n\n`getRaw*Map` methods provide a raw interface which returns Buffers, so we had to parse the values ourselves. But there are also high-level versions that take a *conversion object*. For convenience, `bpf` provides a conversion for uint32, so we can write:\n\n~~~ typescript\nconst { u32type } = require('bpf')\n\nconst dist = bpf.getArrayMap('dist', u32type)\nconst distLinear = bpf.getArrayMap('dist_linear', u32type)\n\nconsole.log( [...dist] )\n~~~\n\nRefer to the [`bpf`][] module for details on the interface.\n\nThe full source code of this example is in [`bitehist.ts`](examples/bitehist.ts).\nRemember you'll probably need root to run.\n\n\n## Troubleshooting\n\nRemember that not all features may be available in the kernel you are running, even if they're present in the API and typings. Trying to use a non-available feature will generally result in an `EINVAL` error.\n\nA reference of eBPF features and minimum kernel versions required for them can be found **[here](https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md)**.\n\n\n\n[`bpf`]: https://github.com/mildsunrise/node_bpf\n[`loadSync`]: https://bpfcc.alba.sh/docs/modules.html#loadSync\n[`load`]: https://bpfcc.alba.sh/docs/modules.html#load\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmildsunrise%2Fnode_bpfcc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmildsunrise%2Fnode_bpfcc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmildsunrise%2Fnode_bpfcc/lists"}