Skip to content
Back to search

ghostscope

DWARF-aware eBPF tracer for source-level userspace tracing - Explore in a TUI or automate with a scriptable CLI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/swananan/ghostscope with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/swananan/ghostscope'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/swananan--ghostscope/badge.svg)](/listings/swananan--ghostscope)

HTML

<a href="/listings/swananan--ghostscope"><img src="/api/listings/swananan--ghostscope/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- [**Installation Guide**](docs/install.md) System requirements and setup

- [**Quick Tutorial**](docs/tutorial.md) Learn the basics in 10 minutes

- [**Tool Comparison**](docs/comparison.md) Choose between GhostScope, perf, GDB, bpftrace, and SystemTap

- [**FAQ**](docs/faq.md) Common questions answered

- [**Limitations**](docs/limitations.md) Known limitations and constraints

- [**Value Diagnostics**](docs/value-diagnostics.md) Understand unavailable values, read failures, display fallbacks, and capture limits; read offline with `ghostscope --value-diagnostics-help`

</td> <td width="33%" valign="top">

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 318 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/logo.png" alt="GhostScope Logo" width="200"/>
  3. <h1 style="margin-top: 0.2em;">GhostScope</h1>
  4. <h3>⚡ Next-generation eBPF userspace runtime tracer</h3>
  5. <p>
  6. <strong>Printf debugging evolved</strong> — Real-time tracing without stop-the-world inspection.
  7. </p>
  8. <p>
  9. <img src="https://img.shields.io/badge/version-0.1.7-blue.svg" alt="Version"/>
  10. <img src="https://img.shields.io/badge/license-GPL--3.0--only%20OR%20MIT-green.svg" alt="License: GPL-3.0-only OR MIT"/>
  11. <img src="https://img.shields.io/badge/Linux-4.4+-orange.svg" alt="Linux 4.4+"/>
  12. <img src="https://img.shields.io/badge/Rust-1.98.0-red.svg" alt="Rust 1.98.0"/>
  13. </p>
  14. <p>
  15. <a href="README-zh.md"><strong>中文文档</strong></a>
  16. </p>
  17. </div>
  18. <br />
  19. ## Overview
  20. GhostScope is a **source-aware userspace tracer** for live Linux processes. With DWARF debug info, it lets you attach at function, source-line, or instruction granularity, print the values that matter, and emit source-aware call stacks without debugger-controlled suspension of the target.
  21. C has the strongest end-to-end coverage. For Rust targets, GhostScope provides targeted support for common values and demangles application, standard-library, and inline backtrace frames. See [Source Language Support](docs/scripting.md#source-language-support) and [Limitations](docs/limitations.md#1-language-support) for the exact boundaries.
  22. > *"The most effective debugging tool is still careful thought, coupled with judiciously placed print statements."* — Brian Kernighan
  23. ### When To Use GhostScope
  24. - You are diagnosing a production service that must stay online: GDB-style stop-the-world debugging would cause too much disruption, and you prefer an eBPF-based workflow with stronger safety boundaries and lower overhead than traditional kernel-module instrumentation.
  25. - You need source-line probes that can read real locals, parameters, globals, and complex data, not just function entry arguments.
  26. - You want DWARF-unwound stack backtraces from the same live probe that prints the relevant state.
  27. - You need to explain how execution reached a specific source line, function, request, or code path without stop-the-world inspection.
  28. - You want a low-friction path from "I wish I had one more printf here" to a repeatable CLI trace script.
  29. ### When Not To Use GhostScope
  30. - Use GDB when you want an interactive debugging experience with breakpoints, single-stepping, memory writes, or coredump debugging.
  31. - Use `perf probe` when you want a quick one-off probe at a function, source line, or local variable inside the perf ecosystem.
  32. - Use bpftrace or SystemTap when you want broad kernel + userspace event aggregation in one script.
  33. - Do not expect source-level variable tracing to work well without DWARF debug info for the modules you care about.
  34. ### GhostScope vs perf, GDB, bpftrace, and SystemTap
  35. For the full, centrally maintained comparison, see the [Tool Comparison](docs/comparison.md).
  36. You can also refer to the [FAQ](docs/faq.md).
  37. ### AI Runtime Analysis Skill
  38. GhostScope supports two modes: an interactive TUI mode, and a CLI mode built around `--script` and `--script-file`. The latter is the more AI-optimized workflow for automation and agent-driven runtime analysis.
  39. Install the shared skill for Codex or Claude Code:
  40. ```bash
  41. curl -fsSL https://raw.githubusercontent.com/swananan/ghostscope/main/scripts/skills/install_ghostscope_runtime_analysis_skill.sh | bash -s -- --copy
  42. ```
  43. If you already have the repository checked out locally, `./scripts/skills/install_ghostscope_runtime_analysis_skill.sh --copy` works too.
  44. Use `--codex`, `--claude`, or `--all` when you want to force a target. Restart Codex or Claude Code after installation.
  45. When the agent shares your workspace, it can often discover the source checkout path and DWARF/debug-symbol status on its own. If it cannot determine them reliably, it should ask before generating a source-backed trace. Two useful prompt patterns are: ask for the values you want to see, then ask for the call stack that explains how execution reached that point.
  46. Context the agent can discover locally in this example:
  47. - Source checkout: `/mnt/500g/code/openresty/openresty-1.27.1.1/build/nginx-1.27.1`
  48. - Target binary: `/usr/local/openresty/nginx/sbin/nginx`
  49. - Debug info: embedded DWARF is available
  50. #### Prompt 1: Inspect live values
  51. ```text
  52. $ghostscope-runtime-analysis trace the running nginx worker and show the raw request body bytes
  53. ```
  54. Generated command:
  55. ```bash
  56. WORKER_PID=$(pgrep -n -f 'nginx: worker process')
  57. sudo ghostscope -p "$WORKER_PID" --script-file /tmp/ghostscope-nginx-body-discard.gs --script-output plain
  58. ```
  59. Generated script:
  60. ```ghostscope
  61. trace /mnt/500g/code/openresty/openresty-1.27.1.1/build/nginx-1.27.1/src/http/ngx_http_request_body.c:671 {
  62. if size > 0 {
  63. let req_line_len = r.request_line.len;
  64. let body_len = size;
  65. print "src=discard-preread pid={} req={:p} line={:s.req_line_len$} body_len={} body={:x.body_len$}",
  66. $pid, r, r.request_line.data, body_len, r.header_in.pos;
  67. }
  68. }
  69. ```
  70. Demo:
  71. ![Prompt 1 CLI demo](assets/demo-prompt1.gif)
  72. #### Prompt 2: Add call context
  73. ```text
  74. $ghostscope-runtime-analysis trace the running nginx worker and show which request reached ngx_http_process_request, plus the source-aware call stack
  75. ```
  76. Generated command:
  77. ```bash
  78. WORKER_PID=$(pgrep -n -f 'nginx: worker process')
  79. sudo ghostscope -p "$WORKER_PID" --script-file /tmp/ghostscope-nginx-request-stack.gs --script-output pretty
  80. ```
  81. Generated script:
  82. ```ghostscope
  83. trace ngx_http_process_request {
  84. let method_len = r.method_name.len;
  85. let uri_len = r.uri.len;
  86. let line_len = r.request_line.len;
  87. print "nginx pid={} method={:s.method_len$} uri={:s.uri_len$} line={:s.line_len$}",
  88. $pid, r.method_name.data, r.uri.data, r.request_line.data;
  89. bt full;
  90. }
  91. ```
  92. Here `print` answers "what request state reached this probe?", while `bt full` answers "how did nginx get here?" using DWARF-unwound, source-aware stack frames.
  93. Demo:
  94. ![Prompt 2 CLI demo](assets/demo-prompt2.gif)
  95. For best results, make sure the relevant source tree is available, the modules you care about carry DWARF debug information, and GhostScope has the privileges needed to load eBPF programs. When that information is not discoverable locally, the skill should ask for it before generating a source-backed trace. Re-run the same installer after pulling updates; the installed skill is versioned and refreshes automatically when the version changes.
  96. ### The Printf That Should Have Been
  97. GhostScope turns compiled binaries into observable systems. In the TUI, that experience unfolds progressively: first find the function or source line you care about, then inspect the variables visible at that point, enter Script Mode from that location, and finally watch values and call stacks update while the target keeps running. It feels less like a generic dashboard and more like source-guided runtime printf debugging with execution context.
  98. The demo below follows exactly that path on a DWARF-enabled nginx worker: locate the code path, drop a trace at the right line, add a small script, and immediately see conditional logic, source-oriented variable access, call-stack context, and live output from the running process.
  99. <br />
  100. <div align="center">
  101. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/demo.gif" alt="GhostScope Demo" width="100%"/>
  102. <p><sub><i>Real-time tracing of a running nginx worker process</i></sub></p>
  103. </div>
  104. ### How It Works
  105. Imagine navigating a vast, uncharted forest of binary data — memory addresses, register values, stack frames — all meaningless numbers without context. **DWARF debug information is our map**: it tells us that stack address `RSP-0x18` stores local variable `count`, heap address `0x5621a8c0` is a `user` object with string pointer `user.name` at offset `+0x20`; it tracks where each variable lives throughout program execution — parameter `x` is in register `RDI` now but will move to stack offset `RSP-0x10` later.
  106. With this map in hand, GhostScope leverages **eBPF and uprobe** technology to safely extract binary data from instruction points in your running program. The combination is powerful: DWARF reveals the meaning of bytes in the process's virtual address space, while eBPF retrieves the requested data. The result is source-aware variable values and call stacks without debugger-controlled suspension or intentional application-state changes. Each uprobe hit still adds synchronous trap and eBPF work, so tracing is not timing-transparent.
  107. ## ✨ Highlights
  108. <div align="center">
  109. <table>
  110. <tr>
  111. <td align="center" width="25%">
  112. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/performance.svg" width="60" alt="Performance"/>
  113. <br />
  114. <strong>Targeted Overhead</strong>
  115. <br />
  116. <sub>Per-hit uprobe + bounded eBPF work</sub>
  117. </td>
  118. <td align="center" width="25%">
  119. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/realtime.svg" width="60" alt="Real-time"/>
  120. <br />
  121. <strong>Real-Time Tracing</strong>
  122. <br />
  123. <sub>Live trace streaming</sub>
  124. </td>
  125. <td align="center" width="25%">
  126. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/dwarf.svg" width="60" alt="DWARF"/>
  127. <br />
  128. <strong>DWARF-Aware</strong>
  129. <br />
  130. <sub>PC-specific source semantics</sub>
  131. </td>
  132. <td align="center" width="25%">
  133. <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/rust.svg" width="60" alt="Rust"/>
  134. <br />
  135. <strong>Rust-Aware Tracing</strong>
  136. <br />
  137. <sub>Targeted values & demangled frames</sub>
  138. </td>
  139. </tr>
  140. </table>
  141. </div>
  142. ## ⚠️ Reliability and Development Status
  143. > **GhostScope is currently in early development** and under active iteration. Within the supported envelope, a known inability to recover or attribute data should be reported explicitly rather than rendered as a plausible value.
  144. >
  145. > Implementation defects may still violate that contract. Use GhostScope's collected data as an **auxiliary reference** for troubleshooting, and cross-validate with other debugging tools before making critical decisions.
  146. >
  147. > The normative guarantees, assumptions, and failure semantics are documented in [Design Guarantees and Trust Model](docs/design-contract.md).
  148. See [Limitations](docs/limitations.md) for unsupported and explicitly degraded scenarios.
  149. ## 📚 Documentation
  150. <table>
  151. <tr>
  152. <td width="33%" valign="top">
  153. ### 🎯 Getting Started
  154. - [**Installation Guide**](docs/install.md)
  155. System requirements and setup
  156. - [**Quick Tutorial**](docs/tutorial.md)
  157. Learn the basics in 10 minutes
  158. - [**Tool Comparison**](docs/comparison.md)
  159. Choose between GhostScope, perf, GDB, bpftrace, and SystemTap
  160. - [**FAQ**](docs/faq.md)
  161. Common questions answered
  162. - [**Limitations**](docs/limitations.md)
  163. Known limitations and constraints
  164. - [**Value Diagnostics**](docs/value-diagnostics.md)
  165. Understand unavailable values, read failures, display fallbacks, and capture limits;
  166. read offline with `ghostscope --value-diagnostics-help`
  167. </td>
  168. <td width="33%" valign="top">
  169. ### ⚙️ Configuration
  170. - [**Configuration Reference**](docs/configuration.md)
  171. All configuration options
  172. - [**TUI Reference**](docs/tui-reference.md)
  173. Complete keyboard shortcuts and panel navigation
  174. - [**Command Reference**](docs/input-commands.md)
  175. All available commands for Input Mode
  176. - [**Script Language**](docs/scripting.md)
  177. Write trace scripts; read offline with `ghostscope --script-help`
  178. </td>
  179. <td width="33%" valign="top">
  180. ### 👨‍💻 Development
  181. - [**Architecture Overview**](docs/architecture.md)
  182. System design and internals
  183. - [**Design Guarantees and Trust Model**](docs/design-contract.md)
  184. Supported operating envelope, invariants, and failure semantics
  185. - [**Development Guide**](docs/development.md)
  186. Build and extend GhostScope
  187. - [**Contributing Guide**](docs/contributing.md)
  188. Join the community
  189. - [**Roadmap**](docs/roadmap.md)
  190. Planned features and milestones
  191. </td>
  192. </tr>
  193. </table>
  194. ## 🤝 Contributing
  195. We welcome contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions, we appreciate your help in making GhostScope better.
  196. Please see our [Contributing Guide](docs/contributing.md) for:
  197. - Code of Conduct
  198. - Development workflow
  199. - Coding standards
  200. - How to submit pull requests
  201. ## 📜 License
  202. GhostScope is dual-licensed under the [GNU General Public License, version 3 only](LICENSE-GPL)
  203. or the [MIT License](LICENSE-MIT), at your option (`GPL-3.0-only OR MIT`).
  204. Third-party components retain their respective licenses. GPL-compatible declarations
  205. for loading eBPF programs into the Linux kernel are retained; see [LICENSE](LICENSE).
  206. ## 🙏 Acknowledgements
  207. Built with amazing open source projects:
  208. - [**Aya**](https://aya-rs.dev/) - eBPF library for Rust (using its loader functionality)
  209. - [**LLVM**](https://llvm.org/) - Compiler infrastructure
  210. - [**Inkwell**](https://github.com/TheDan64/inkwell) - Safe LLVM bindings for Rust
  211. - [**Gimli**](https://github.com/gimli-rs/gimli) - DWARF parser
  212. - [**Ratatui**](https://ratatui.rs/) - Terminal UI framework
  213. - [**Tokio**](https://tokio.rs/) - Async runtime
  214. - [**Pest**](https://github.com/pest-parser/pest) - PEG parser generator
  215. Inspired by and learned from:
  216. - [**GDB**](https://www.gnu.org/software/gdb/) - DWARF parsing optimizations
  217. - [**bpftrace**](https://github.com/iovisor/bpftrace) - eBPF tracing techniques
  218. - [**cgdb**](https://cgdb.github.io/) - TUI design and user experience
  219. Special thanks to these excellent resources that taught us a lot:
  220. **Blog Posts:**
  221. - [**The Wonderland of Dynamic Tracing**](https://blog.openresty.com/en/dynamic-tracing-part-1/)
  222. - [**Unwinding the Stack the Hard Way**](https://lesenechal.fr/en/linux/unwinding-the-stack-the-hard-way)
  223. **Books:**
  224. - [**Crafting Interpreters**](https://craftinginterpreters.com/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.