{"id":31768831,"url":"https://github.com/swananan/ghostscope","last_synced_at":"2026-05-18T03:11:30.508Z","repository":{"id":318659616,"uuid":"1045560846","full_name":"swananan/ghostscope","owner":"swananan","description":"DWARF-aware eBPF tracer for source-level userspace tracing - Explore in a TUI or automate with a scriptable CLI","archived":false,"fork":false,"pushed_at":"2026-05-10T06:25:17.000Z","size":35422,"stargazers_count":173,"open_issues_count":1,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-10T08:25:25.382Z","etag":null,"topics":["debugger","dwarf","ebpf","gdb","rust","tracer"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swananan.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-27T11:20:47.000Z","updated_at":"2026-05-10T06:17:50.000Z","dependencies_parsed_at":"2025-10-08T14:40:51.058Z","dependency_job_id":null,"html_url":"https://github.com/swananan/ghostscope","commit_stats":null,"previous_names":["swananan/ghostscope"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/swananan/ghostscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swananan%2Fghostscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swananan%2Fghostscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swananan%2Fghostscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swananan%2Fghostscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swananan","download_url":"https://codeload.github.com/swananan/ghostscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swananan%2Fghostscope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33163444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"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":["debugger","dwarf","ebpf","gdb","rust","tracer"],"created_at":"2025-10-10T02:15:26.479Z","updated_at":"2026-05-18T03:11:30.501Z","avatar_url":"https://github.com/swananan.png","language":"Rust","funding_links":[],"categories":["Projects Related to eBPF"],"sub_categories":["Tools"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/logo.png\" alt=\"GhostScope Logo\" width=\"200\"/\u003e\n  \u003ch1 style=\"margin-top: 0.2em;\"\u003eGhostScope\u003c/h1\u003e\n  \u003ch3\u003e⚡ 下一代 eBPF 用户态运行时追踪器\u003c/h3\u003e\n  \u003cp\u003e\n    \u003cstrong\u003ePrintf 调试的进化\u003c/strong\u003e — 无需停止或修改应用即可实时追踪。\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/版本-0.1.4-blue.svg\" alt=\"版本\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/协议-GPL-green.svg\" alt=\"协议\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Linux-4.4+-orange.svg\" alt=\"Linux 4.4+\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Rust-1.88.0-red.svg\" alt=\"Rust 1.88.0\"/\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## 概述\n\nGhostScope 是一个 **面向源码语义的用户态追踪器**。有 DWARF 调试信息时，它可以在不停住目标进程的前提下，按函数、源码行或指令粒度设点，并打印真正重要的信息。\n\n\u003e *\"The most effective debugging tool is still careful thought, coupled with judiciously placed print statements.\"* — Brian Kernighan\n\n### 什么时候适合用 GhostScope\n\n- 你在排查线上正在运行的服务，不能接受 GDB 式 stop-the-world 带来的巨大性能扰动，同时又更希望使用基于 eBPF 的工作流，获得比传统内核模块式探测更好的安全边界和更低开销。\n- 你关心的是源码行和真实变量值，而不只是函数入口参数。\n- 你想把“这里要是能加一条 printf 就好了”快速变成一个可运行的追踪脚本。\n- 你希望让 AI agent 基于 GhostScope 文档、源码路径和 DWARF 二进制直接产出追踪命令。\n\n### 什么时候不适合用 GhostScope\n\n- 如果你需要带断点、单步、改内存或调 coredump 的交互式调试体验，用 GDB。\n- 如果你想在 perf 生态里快速对某个函数、源码行或局部变量打一针式 probe，用 `perf probe`。\n- 如果你要在同一套脚本里混合大量内核 + 用户态事件做聚合，优先考虑 bpftrace 或 SystemTap。\n- 如果目标模块没有 DWARF 调试信息，就不要期待源码级变量追踪能很好地工作。\n\n### GhostScope 和 perf、GDB、bpftrace、SystemTap 的区别\n\n完整、统一维护的对比请看 [工具对比](docs/zh/comparison.md)。另外也可以参考 [常见问题](docs/zh/faq.md)。\n\n### AI 运行时分析 Skill\n\nGhostScope 支持两种模式：一种是交互式 TUI 模式，另一种是基于 `--script` 和 `--script-file` 的 CLI 模式。后者是更适合 AI 和自动化的工作流。\n\n给 Codex 或 Claude Code 安装共享 skill：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/swananan/ghostscope/main/scripts/skills/install_ghostscope_runtime_analysis_skill.sh | bash -s -- --copy\n```\n\n如果你已经把仓库 clone 到本地，也可以继续使用 `./scripts/skills/install_ghostscope_runtime_analysis_skill.sh --copy`。\n\n如果你想强制指定目标，可以追加 `--codex`、`--claude` 或 `--all`。安装后需要重启 Codex 或 Claude Code。\n\n当 AI 和你共享同一个 workspace 时，它通常可以自己发现源码 checkout 路径以及 DWARF/调试符号状态。只有在这些信息无法可靠判断时，它才应该先追问，再生成带源码依据的结果。一个典型的会话可以拆成四步。\n\n这个例子里，AI 可以在本地自行发现的上下文：\n\n- 源码 checkout：`/mnt/500g/code/openresty/openresty-1.27.1.1/build/nginx-1.27.1`\n- 目标二进制：`/usr/local/openresty/nginx/sbin/nginx`\n- 调试信息状态：二进制内带有 DWARF 调试信息\n\n提问：\n\n```text\n$ghostscope-runtime-analysis 跟踪正在运行的 nginx worker，并把请求 body 的原始字节打印出来\n```\n\n生成的命令：\n\n```bash\nWORKER_PID=$(pgrep -n -f 'nginx: worker process')\nsudo ghostscope -p \"$WORKER_PID\" --script-file /tmp/ghostscope-nginx-body-discard.gs --script-output plain\n```\n\n生成的脚本：\n\n```ghostscope\ntrace /mnt/500g/code/openresty/openresty-1.27.1.1/build/nginx-1.27.1/src/http/ngx_http_request_body.c:671 {\n    if size \u003e 0 {\n        let req_line_len = r.request_line.len;\n        let body_len = size;\n\n        print \"src=discard-preread pid={} req={:p} line={:s.req_line_len$} body_len={} body={:x.body_len$}\",\n            $pid, r, r.request_line.data, body_len, r.header_in.pos;\n    }\n}\n```\n\n演示效果：\n\n![GhostScope CLI 演示](assets/demo-cli.gif)\n\n为了得到最好效果，请确保相关源码树可用、你关心的模块带有 DWARF 调试信息，并且 GhostScope 具备加载 eBPF 程序所需的权限。如果这些信息无法在本地可靠发现，skill 应该先追问，再生成带源码依据的追踪结果。拉取仓库更新后，重新执行同一个安装脚本即可；安装的 skill 自带版本号，版本变化时会自动刷新。\n\n### 理想中的 Printf\n\nGhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 里，这个过程是递进展开的：先定位到感兴趣的函数或源码行，看清楚当前可见的变量，再从那个位置进入 Script Mode 设点，最后一边让目标进程继续运行，一边在输出面板里看实时结果。它不是一个泛泛的监控面板，而是一个沿着源码路径逐步展开的运行时 printf 调试界面。\n\n下面这个演示就是按这条路径展开的：先在带 DWARF 的 nginx worker 里找到目标代码，再在对应行写一小段脚本，最后立刻看到条件判断、按源码语义访问变量，以及运行中进程的实时输出。\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/demo.gif\" alt=\"GhostScope Demo\" width=\"100%\"/\u003e\n  \u003cp\u003e\u003csub\u003e\u003ci\u003e实时追踪运行中的 nginx worker 进程\u003c/i\u003e\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n### 工作原理\n\n想象一下，你面对的是一片广袤的二进制数据荒野 —— 内存地址、寄存器值、栈帧数据 —— 没有上下文，它们只是毫无意义的数字。**DWARF 调试信息就是我们的地图**：它告诉我们栈地址 `RSP-0x18` 存储着局部变量 `count`，堆地址 `0x5621a8c0` 处的结构体是 `user` 对象，其偏移 `+0x20` 处是字符串指针 `user.name`；它追踪每个变量在程序执行过程中的位置变化 —— 参数 `x` 现在在寄存器 `RDI` 中，之后会被移到栈上 `RSP-0x10` 的位置。\n\n有了这张地图，GhostScope 利用 **eBPF 和 uprobe** 技术从运行中程序的指令点安全地提取二进制数据。这种组合威力强大：DWARF 揭示进程虚拟地址空间中数据的含义，eBPF 安全地获取我们需要的数据。结果呢？你可以在不停止、不修改程序的情况下打印变量值（局部变量或全局变量）、函数参数和复杂数据结构。\n\n## ✨ 核心特性\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" width=\"25%\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/performance.svg\" width=\"60\" alt=\"Performance\"/\u003e\n        \u003cbr /\u003e\n        \u003cstrong\u003e低开销\u003c/strong\u003e\n        \u003cbr /\u003e\n        \u003csub\u003e仅需一次上下文切换 + eBPF 执行\u003c/sub\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"25%\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/realtime.svg\" width=\"60\" alt=\"Real-time\"/\u003e\n        \u003cbr /\u003e\n        \u003cstrong\u003e实时追踪\u003c/strong\u003e\n        \u003cbr /\u003e\n        \u003csub\u003e实时跟踪流\u003c/sub\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"25%\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/dwarf.svg\" width=\"60\" alt=\"DWARF\"/\u003e\n        \u003cbr /\u003e\n        \u003cstrong\u003eDWARF 感知\u003c/strong\u003e\n        \u003cbr /\u003e\n        \u003csub\u003e完整调试信息支持\u003c/sub\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"25%\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/rust.svg\" width=\"60\" alt=\"Rust\"/\u003e\n        \u003cbr /\u003e\n        \u003cstrong\u003eRust 构建\u003c/strong\u003e\n        \u003cbr /\u003e\n        \u003csub\u003e内存安全且极速\u003c/sub\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n## ⚠️ 实验性工具声明\n\n\u003e **GhostScope 目前处于早期开发阶段**，仍在积极迭代中。虽然我们努力确保数据准确性，但在某些情况下可能出现错误或不完整的追踪信息，更多的应该是探测功能不支持。\n\u003e\n\u003e **建议**：将 GhostScope 采集的数据作为问题排查的**辅助参考**，而非唯一依据。在做出关键决策前，请结合其他调试工具交叉验证。\n\u003e\n\u003e 我们正在持续改进稳定性和准确性，期待未来版本能够移除此声明。\n\n当前的硬性限制和软性限制，请参阅 [使用限制](docs/zh/limitations.md)。\n\n## 📚 文档\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### 🎯 入门指南\n\n- [**安装指南**](docs/zh/install.md)\n  系统要求和设置\n\n- [**快速教程**](docs/zh/tutorial.md)\n  10分钟学习基础知识\n\n- [**工具对比**](docs/zh/comparison.md)\n  在 GhostScope、perf、GDB、bpftrace 和 SystemTap 之间做选择\n\n- [**常见问题**](docs/zh/faq.md)\n  常见问题解答\n\n- [**使用限制**](docs/zh/limitations.md)\n  已知的限制和约束\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### ⚙️ 配置\n\n- [**配置参考**](docs/zh/configuration.md)\n  所有配置选项\n\n- [**TUI 参考手册**](docs/zh/tui-reference.md)\n  完整的快捷键和面板导航\n  \n\n- [**命令参考**](docs/zh/input-commands.md)\n  输入模式所有可用命令\n\n- [**脚本语言**](docs/zh/scripting.md)\n  编写强大的追踪脚本\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### 👨‍💻 开发\n\n- [**架构概览**](docs/zh/architecture.md)\n  系统设计和内部原理\n\n- [**开发指南**](docs/zh/development.md)\n  构建和扩展 GhostScope\n\n- [**贡献指南**](docs/zh/contributing.md)\n  加入社区\n\n- [**未来规划**](docs/zh/roadmap.md)\n  里程碑\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 🤝 贡献\n\n我们欢迎贡献！无论是错误报告、功能请求、文档改进还是代码贡献，我们都感谢您帮助改进 GhostScope。\n\n请查看我们的[贡献指南](docs/zh/contributing.md)了解：\n- 行为准则\n- 开发工作流\n- 编码标准\n- 如何提交拉取请求\n\n## 📜 许可证\n\nGhostScope 采用 [GNU 通用公共许可证](LICENSE) 授权。\n\n## 🙏 致谢\n\n使用以下优秀的开源项目构建：\n\n- [**Aya**](https://aya-rs.dev/) - Rust 的 eBPF 库（使用其 loader 功能）\n- [**LLVM**](https://llvm.org/) - 编译器基础设施\n- [**Inkwell**](https://github.com/TheDan64/inkwell) - Rust 的安全 LLVM 绑定\n- [**Gimli**](https://github.com/gimli-rs/gimli) - DWARF 解析器\n- [**Ratatui**](https://ratatui.rs/) - 终端 UI 框架\n- [**Tokio**](https://tokio.rs/) - 异步运行时\n- [**Pest**](https://github.com/pest-parser/pest) - PEG 解析器生成器\n\n受到以下项目的启发和借鉴：\n\n- [**GDB**](https://www.gnu.org/software/gdb/) - DWARF 解析优化\n- [**bpftrace**](https://github.com/iovisor/bpftrace) - eBPF 追踪技术\n- [**cgdb**](https://cgdb.github.io/) - TUI 设计和用户体验\n\n特别感谢以下优秀资源，从中学到了很多：\n\n**博客文章：**\n- [**动态追踪漫谈**](https://blog.openresty.com.cn/cn/dynamic-tracing/)\n- [**Unwinding the stack the hard way**](https://lesenechal.fr/en/linux/unwinding-the-stack-the-hard-way)\n\n**技术书籍：**\n- [**Crafting Interpreters**](https://craftinginterpreters.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswananan%2Fghostscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswananan%2Fghostscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswananan%2Fghostscope/lists"}