可观测性性能剖析eBPF【免费下载链接】bpftraceHigh-level tracing language for Linux项目地址https://gitcode.com/gh_mirrors/bp/bpftrace点击查看免费下载bpftrace 是一个面向 Linux 的高层跟踪语言致力于让开发者用极简的单行命令快速编写基于 eBPF 的可观测性程序。本文以仓库根目录的 CONTRIBUTING.md 为主线结合 docs/developers.md、tests/README.md、docs/coding_guidelines.md 与 docs/release_process.md 等配套文档系统讲解 bpftrace 社区的贡献方式如何提交问题、如何编写并分享 bpftrace 工具、如何搭建开发环境与构建、如何通过 RFC 流程推进重大变更、如何保证提交质量并通过 DCO 签名完成合规贡献。读完本文你将掌握从提一个 Issue到代码成功合入 master的完整路径以及每个环节背后的仓库级实现依据。一、参与贡献的入口Issue、IRC 与 Good First Issuesbpftrace 对贡献持开放态度Contributions are welcome任何形式的参与都被欢迎包括Bug 报告与功能请求通过 GitHub Issue Tracker 提交。开发讨论参与 #bpftrace 的 IRC 频道irc.oftc.net用于社区与开发者之间的实时交流。新手任务带有good first issue标签的 Issue 专为初次贡献者设计适合作为入门切入点。从仓库现状看good first issue通常涉及小范围改动比如修正文档、修复特定内置函数的边界情况等可以直接走普通的 GitHub pull request 工作流无需走 RFC 流程。二、贡献工具写自己的 bpftrace 工具并分享bpftrace 社区鼓励每个人编写并分享自己的 bpftrace 工具Contributing Tools工具可以托管在任何你喜欢的地方没有强制约束。对于希望与社区共享的工具有两个去向社区工具仓库user-tools repository这是一个社区中心任何人不经主仓库审核即可提交自己写的工具适合那些功能明确、面向特定场景的脚本。主仓库的 tools/ 目录这是由维护者精选的一小撮示例集合具有以下特征见 tools/README.md经过生产环境实战检验battle-tested in production随 bpftrace 一起打包分发同时承担测试与验证职责——tools/下每个.bt脚本都会在**工具解析测试tool parsing tests**中被逐一执行确保它们始终语法有效、可运行。这意味着如果你的工具希望进入主仓库不仅要代码正确还要能够持续通过自动化的工具解析测试。仓库中 scripts/bpftrace_tidy.sh 可用于格式化.bt脚本使其符合 bpftrace 自身的代码风格。三、开发环境准备clone、内核依赖与特性检查3.1 初始化子模块bpftrace 使用 git submodule 管理第三方依赖最典型的是 libbpf/ 子模块参见 docs/dependency_support.md因此在检出代码时必须初始化子模块git clone --recurse-submodules https://github.com/bpftrace/bpftrace cd bpftrace3.2 Linux 内核要求bpftrace 最大的运行时依赖是 Linux 内核。根据 docs/dependency_support.md当前仓库要求的最低内核版本为 6.1并建议支持稳定内核与最近 4 个 LTS 内核。需要更老内核支持的用户可以回退使用旧版本 bpftrace。内核必须以正确选项构建关键配置项包括CONFIG_BPFy CONFIG_BPF_SYSCALLy CONFIG_BPF_JITy CONFIG_HAVE_EBPF_JITy CONFIG_BPF_EVENTSy CONFIG_FTRACE_SYSCALLSy CONFIG_FUNCTION_TRACERy CONFIG_HAVE_DYNAMIC_FTRACEy CONFIG_DYNAMIC_FTRACEy CONFIG_HAVE_KPROBESy CONFIG_KPROBESy CONFIG_KPROBE_EVENTSy CONFIG_ARCH_SUPPORTS_UPROBESy CONFIG_UPROBESy CONFIG_UPROBE_EVENTSy CONFIG_DEBUG_FSy上述配置可以通过仓库提供的 scripts/check_kernel_features.sh 一键核验。该脚本会依次尝试读取命令行参数指定的配置文件、/boot/config-$(uname -r)、/boot/config与/proc/config.gz并逐个zgrep检查上面的每个选项是否为y源码见 scripts/check_kernel_features.sh./scripts/check_kernel_features.sh # 输出示例 # All required features present!如果缺少选项脚本会逐条打印缺失项并以非零码退出。内核选项齐备后最好再确认系统没有启用 kernel lockdown常见于启用 Secure Boot 的环境否则 bpftrace 会被内核拒绝运行具体排查方法见下文构建与疑难排障。四、构建 bpftraceNix 优先发行版兜底4.1 Nix 构建推荐Nix 是 bpftrace 官方推荐的构建方式也是 CI 所使用的构建环境。Nix 会全量托管所有构建与运行时依赖理论上保证近乎 100% 的可复现性且开发者无需手动安装任何构建/运行包。所有 Nix 构建与测试命令都需要在 Nix dev shell 内执行nix develop # 进入 dev shell mkdir build cmake -B build -DCMAKE_BUILD_TYPEDebug make -C build -j$(nproc)使用不同 LLVM 版本开发nix develop .#bpftrace-llvm21仓库 flake.nix 中默认 LLVM 为最新受支持版本并为 x86_64-linux 与 aarch64-linux 提供多版本产物。更多 Nix 示例静态构建、fuzzing、flake 管理见 docs/nix.md。4.2 发行版构建发行版构建依赖你在宿主系统上自行安装 bpftrace 的全部构建与运行依赖然后调用 cmake。需要注意 bpftrace 对libbpf和bcc的新版本有严格依赖且会紧跟其上游进展因此在包较新的发行版上发行版构建通常工作良好在包滞后的发行版如 Debian上建议改用 Nix 构建或手动编译安装新版bcc与libbpf。仓库提供了多份 Dockerfile 作为依赖清单参考docker/Dockerfile.ubuntu、docker/Dockerfile.fedora、docker/Dockerfile.debian另有 alpine、opensuse、static 变体。依赖装好后mkdir build cmake -B build -DCMAKE_BUILD_TYPERelease make -C build -j$(nproc)关键 cmake 选项-DBUILD_TESTINGON默认开启会生成bpftrace_test等测试目标-DLLVM_REQUESTED_VERSIONmajor指定 LLVM 主版本。4.3 构建产物与疑难排障构建产物位于build/src/bpftrace。Kernel Lockdown若系统启用了内核 lockdown常伴随 Secure Bootbpftrace 会被阻止运行。解决方式在 UEFI 中关闭 Secure Boot或执行sudo mokutil --disable-validation后重启或用SysRQx临时解除 lockdown仅持续到下次启动。五、RFC 流程重大变更的标准路径这是 CONTRIBUTING.md 的核心章节之一适用于重大substantial或破坏性breaking变更。Bug 修复、文档更新、小功能以及带good first issue标签的问题直接走普通 PR 工作流即可无需 RFC。完整的 RFC 流程分三步5.1 第一步创建 RFC Issue新建一个 Issue标题以 RFC 为前缀并打上 RFC 标签。Issue 中必须包含变更的目标goal(s)潜在的缺点potential downsides如适用你考虑过的其他方案other solutions youve considered。该 Issue 是整体设计与方案讨论的场所。实现细节不应在此讨论因为实现细节往往容易引发对整体提案的旁枝末节式争论bike-shedding。5.2 第二步提交 POC 与 PR当获得一位或多位维护者的正面信号、或没有负面信号时可以创建 POC概念验证就绪后提交 pull request并在 PR 中链接原始 RFC Issue。这是让其他人实验你的 POC、讨论实现细节的好时机。需要特别留意两点POC 可能暴露原 RFC 方案的缺陷这是完全正常的。回到原始 RFC解释为什么已批准方案不适用或需要调整。若改动足够大维护者可能要求对 RFC 上的新方案做额外批准RFC 最终被拒绝也是正常的开发过程。配置开关config flag视改动规模而定维护者可能要求将该特性放在 config flag 之后即用户必须在脚本中显式 opt-in例如config { unstable_my_featuretrue }这样可以在不永久加入语言的前提下提高开发速度、等待更多用户反馈。需要注意的是这类特性仍可能因为用户反馈或设计方向变化而被移除、最终未进入语言但维护者会与原作者充分沟通。5.3 第三步POC 获批后的 PR 清单当 POC 获得两位或以上维护者批准后请遵循当前的 PR 清单更新 CHANGELOG.md把本次用户可见的变更写入 changelog格式遵循 Keep a Changelog章节按Added/Changed/Fixed等组织更新 adoc 文档即 man/adoc/bpftrace.adoc 中的语言/命令参考保证单元测试与运行时测试齐备具体测试类型与写法见下一节。六、测试每个贡献的四道关卡CONTRIBUTING.md 强调Every contribution should (1) not break the existing tests and (2) introduce new tests if relevant。bpftrace 共有四类测试详见 tests/README.md类型位置运行方式说明单元测试Unittests/*.cppsudo builddir/tests/bpftrace_test基于 GoogleTest覆盖语义分析器、codegen 等组件可用--gtest_filter或GTEST_FILTER筛选自测试Selftests/self/sudo builddir/tests/self-tests.sh用test:探针测试核心功能与标准库单文件调试可用builddir/src/bpftrace --test file用--probe-filter REGEX按名称筛选运行时测试Runtimetests/runtime/非 Nixsudo builddir/tests/runtime-tests.shNixsudo --preserve-envPATH --preserve-envPYTHONPATH ./build/tests/runtime-tests.sh调用真实 bpftrace 可执行文件按套件通常是单个文件分组工具解析测试Tool parsingtools/sudo builddir/tests/tools-parsing-test.sh逐一执行tools/下所有工具确保其合法可运行6.1 运行时测试指令速查运行时测试用一组指令directive描述测试用例以下是最常用的几个NAME用例名必填。RUN或PROG二选一必填。PROG直接给 bpftrace 程序多行程序按首行列对齐RUN在 shell 中执行命令。EXPECT/EXPECT_NONE/EXPECT_REGEX/EXPECT_REGEX_NONE期望输出分别对应整行字面匹配、否定、正则匹配、正则否定还有文件匹配EXPECT_FILE与 JSON 匹配EXPECT_JSON。TIMEOUT用例超时秒必填。BEFORE/AFTER/SETUP/CLEANUP分别在 bpftrace 运行前/后、测试前后执行 shell 命令用于拉起被测程序或清理资源。BEFORE会阻塞等待到与命令最后一个空格分隔 token 同名的进程出现 PID。REQUIRES/REQUIRES_FEATURE条件执行前者执行 shell 命令成功才运行用例后者检查 bpftrace 特性见bpftrace --info与 tests/runtime/engine/runner.py。MIN_KERNEL/MAX_KERNEL/ARCH内核版本与架构过滤ARCH支持|逻辑或、be/le端序匹配与!否定前缀。ENV为 bpftrace 调用注入NAMEVALUE环境变量。NEW_PIDNS在挂载 proc 的新 pid 命名空间中执行BEFORE、bpftrace 与AFTER。RETURN_CODE/WILL_FAIL断言退出码/预期非零退出。RUN指令还支持运行时变量占位{{BPFTRACE}}bpftrace 路径、{{BEFORE_PID}}首个BEFORE进程的 PID、{{CWD}}。测试程序放在 tests/testprogs/测试库放在 tests/testlibs/例如tests/testprogs/my_test.c会被构建为可在运行时测试中探测的./testprogs/my_test特别适合 uprobe/USDT 类测试。七、编码规范与代码风格7.1 语义层面的 Coding Guidelinesdocs/coding_guidelines.md 关注的是代码语义与语言特性取舍格式交给 clang-format核心约定包括错误处理可恢复错误通过返回值传递std::optional、int、bool不可恢复错误抛出FatalUserException异常不得用于可恢复错误。例如 map 写入失败map 满、权限不足等是可恢复错误应传播而debugfs未挂载则属于不可恢复错误应直接抛异常告知用户系统未就绪。struct vs. classstruct 仅用于携带数据的被动对象所有字段公开、不持有不变量、无方法其余一律用 class。命名变量使用snake_case私有成员带尾随下划线公开成员与 struct 数据成员不带。日志级别DEBUG始终输出、V1仅-v时输出用于 BTF 不可用之类的警告、HINT紧跟 WARNING/ERROR 的解决提示、WARNING可继续运行但影响行为/输出、ERROR用户输入非法最终经main.cpp捕获FatalUserException后exit(1)、BUG内部非预期问题直接 abort。7.2 代码风格与格式化C 代码用仓库自带的 clang-format 配置格式化可用git clang-format upstream/master便捷格式化提交。bpftrace 语言代码标准库与.bt脚本由 bpftrace 自身格式化bpftrace --fmt或 scripts/bpftrace_tidy.sh。避免单独的 fix formatting 提交每个提交都应自带正确格式否则 CI 会失败。注释风格优先使用 C 风格注释//C 风格注释/* */仅用于单行内的嵌套注释如对某个参数做注解。bpftrace 语言本身两种注释块都支持目前无强制偏好。八、提交、合入与 Changelog8.1 合并策略squash rebaseCONTRIBUTING.md 与 docs/developers.md 都明确了合并约定所有 PR 需 squash rebase不含 merge commit即 master 上每个 PR 只对应一个提交这让 changelog 生成简单且精确、噪音最少。例外对于改动复杂的 PR若提交结构良好也可以 rebase merge仍不含 merge commit。判断标准是提交标题在 changelog 中读起来要说得通。8.2 Changelog 维护changelog 面向最终用户提供对用户重要的变更摘要重构、测试改动等内部变更不写入。为避免发版时突击补写changelog随 PR 一起维护每个有用户影响的 PR 都必须包含 changelog 条目。因为 changelog 格式中包含 PR 号所以条目只能在 PR 打开后补充。单提交 PR 直接并入该提交多提交 PR 可以单独增加一个 changelog 提交。8.3 Developers Certificate of OriginDCO为追踪谁做了什么bpftrace 引入了sign-off签名流程。签名是每个提交末尾的一行证明你编写了该提交、或有权利将其作为开源贡献传递。规则遵循 Developers Certificate of Origin。用git commit的--signoff选项为所有提交签名git commit --signoff --message This is the commit message该选项会在提交日志消息末尾追加Signed-off-by尾注。请使用真实姓名与真实邮箱地址不接受匿名贡献、github 登录名等。九、持续集成与 CI 排障CI 在 NixOS 上以多种 LLVM 版本组成的矩阵执行上述全部测试任务定义在 .github/workflows/ci.yml。CI 会在主仓库的所有分支与 PR 上自动运行官方也建议在你自己的 fork 上启用 GitHub Actions以便对测试分支提前跑 CI。复现 CI 失败环境的步骤从 GHA UI 获取 job 环境设置相关环境变量后运行 .github/include/ci.py。示例$ NIX_TARGET.#bpftrace-llvm10 ./.github/include/ci.py$ NIX_TARGET.#bpftrace-llvm11 \ CMAKE_BUILD_TYPERelease \ RUNTIME_TEST_DISABLEprobe.kprobe_offset_fail_size,usdt.usdt probes - file based semaphore activation multi process \ ./.github/include/ci.py虚拟机测试vmtestsCI 会借助嵌套虚拟化在受控内核下运行一部分运行时测试使用 vmtest 管理虚拟机。上述排障流程同样适用于 vmtest 化的运行时测试。若想在内核中快速手动验证可$ nix develop (nix:nix-shell-env) $ vmtest -k $(nix build --print-out-paths .#kernel-6_12)/bzImage -- ./build/src/bpftrace -V bzImage Booting Setting up VM Running command bpftrace v0.21.0-344-g3acbvmtest 会把当前运行的 userspace 映射进虚拟机因此你可以直接在 guest 中运行宿主上构建的二进制例如你的 bpftrace 开发构建。十、性能测量与更深层参考在贡献过程中若涉及性能敏感路径可以用以下两个模式量化影响见 docs/developers.md编译期性能bpftrace --mode compiler-bench查看编译各 pass 的耗时生成代码性能bpftrace --mode bench配合BENCH探针例如$ bpftrace --mode bench -e BENCH:my_benchmark { a; } Attached 1 probe ---------------------------- | BENCHMARK | AVERAGE TIME | ---------------------------- | my_benchmark | 270ns | ----------------------------更多底层机制参见 docs/internals_development.md。十一、与贡献相关的项目宏观约定虽然 CONTRIBUTING.md 未展开论述但理解下面两份配套文档有助于让你的贡献方向与项目愿景一致设计原则bpftrace 的使命是让不熟悉 eBPF 复杂性的用户也能快速编写基于 BPF 的可观测性程序。语言目标按优先级排序为简洁one-liners、可读、对 eBPF 的干净抽象、快速迭代、可组合、内核与用户态性能良好、启动速度。非目标包括可测试性、可调试性、动态类型、类/继承、元编程、异常处理、以及 BPF 安全/LSM/XDP/调度等领域。重大或破坏性变更会被要求走 RFC 流程这正是 CONTRIBUTING.md 中 RFC Process 一节的依据。发布流程bpftrace 遵循语义化版本每年发布两次与 LLVM 发布节奏对齐minor 版本在 LLVM 主版本发布两周后。了解发布节奏有助于判断你的贡献会落在哪个版本窗口、以及何时该往 release 分支 backportgit cherry-pick -s -x sha1。十二、贡献流程速查清单初始化子模块检出代码用scripts/check_kernel_features.sh验证内核特性小改动直接提 PR重大改动先发 RFC Issue再提交链接 RFC 的 POC PR获两位以上维护者批准后按 PR 清单推进每个贡献不破坏既有测试并酌情新增单元测试、自测试或运行时测试注意TIMEOUT、NAME、RUN/PROG、EXPECT*等必填指令遵循 docs/coding_guidelines.md 的语义规范用 clang-format 与bpftrace --fmt/scripts/bpftrace_tidy.sh保证格式每个提交用git commit --signoff签名真实姓名真实邮箱用户可见变更同步更新 CHANGELOG.md 与 man/adoc/bpftrace.adocPR 保持 squash rebase不产生 merge commit。至此从 Issue 报告、工具编写与分享到 RFC 提案、测试编写、代码合入与 DCO 合规bpftrace 贡献的完整链路已经清晰。无论你贡献的是一个小工具、一次文档修正还是语言级新特性都可以在这套流程中找到自己的位置。赞分享可观测性性能剖析eBPF【免费下载链接】bpftraceHigh-level tracing language for Linux项目地址https://gitcode.com/gh_mirrors/bp/bpftrace点击查看免费下载相关推荐Delve 贡献指南从 Issue 提报到代码合入的完整实践Delve 贡献指南从 Issue 提报到代码合入的完整实践 导读 本文基于 CONTRIBUTING.md https://link.gitcode.com开发工具Mesop 贡献指南从 Issue 到代码合入的完整实践路径Mesop 贡献指南从 Issue 到代码合入的完整实践路径 Mesop 是一个面向 AI 应用开发的 Python Web 框架Rapidly buil前端后端Web框架Magpie 开源贡献指南从报告 Bug、提交功能到编写代码的完整实践Magpie 开源贡献指南从报告 Bug、提交功能到编写代码的完整实践 Magpie 是一款面向 Windows 10/11 的通用窗口超分辨率upscal桌面应用图形学图像处理上一篇Repomix 使用场景实战指南用 AI 完成代码审查、Bug 调查、安全审计与架构分析下一篇使用 cilium-dbg envoy admin listeners 查看 Cilium 中 Envoy 的监听器Listener配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
