Skip to content

tutorial.md

Latest commit

 

History

History
185 lines (128 loc) · 7.44 KB

tutorial.md

File metadata and controls

185 lines (128 loc) · 7.44 KB

GhostScope Tutorial

Learn to trace running applications with GhostScope in 10 minutes!

Quick Start

Launch GhostScope

GhostScope offers two modes for attaching to processes, both using Linux uprobe + eBPF mechanism:

Mode 1: PID-specific tracing (-p)

# Trace a specific running process by PID
sudo ghostscope -p $(pidof your_app)
  • When to use: You have a running process and want to trace only that specific instance
  • Advantage: Focused tracing with less noise from other processes
  • Limitation: Can't catch early startup events

Mode 2: Binary-wide tracing (-t)

# Trace ALL processes using this binary
sudo ghostscope -t /path/to/binary

# Also works with shared libraries
sudo ghostscope -t /usr/lib/libexample.so
  • When to use: You want to catch process startup events or trace multiple instances
  • Advantage: Can capture events from process initialization, perfect for debugging startup issues
  • Note: Will trace ALL processes using this binary/library, which may generate more events

Important Notes

⚠️ Things to know:

  1. The -p option traces the main program and all currently loaded dynamic libraries (libraries loaded later via dlopen are not yet supported)
  2. The executables and libraries you want to trace must contain debug information, otherwise GhostScope will be helpless. How to check? See the Debug Symbols section in the Installation Guide

Understanding the TUI

Starting Up and Loading

After successfully launching GhostScope, you'll see a loading screen — GhostScope is loading debug information and building query indices. This might take some time (loading nginx takes about 3 seconds, for example). Don't ask me why GDB loads so fast, I'm still learning optimization tricks from GDB, hoping to make it faster in future versions.

Loading UI GhostScope's carefully designed loading interface

If all goes well, in the blink of an eye (you might miss the carefully designed loading screen), you'll see GhostScope's TUI interface:

TUI Interface GhostScope TUI main interface

The Three Panels

Here's a brief introduction to GhostScope's TUI panel layout:

1. Source Panel

  • What it shows: Application source code (defaults to the file containing the main function)
  • Purpose: Browse code and set trace points

2. eBPF Output Panel

  • What it shows: Real-time trace output
  • Purpose: View execution traces as they happen

3. Command Panel

  • What it shows: Command input line
  • Purpose: Enter trace commands and control session

Core Operations

Here are the two main ways to use GhostScope, as demonstrated in the README.

Command Panel's Three Modes

Focus defaults to the Command Panel, which has three modes:

1. Input Mode (Default)

In input mode, you can execute various commands. For example:

trace {target}  # target can be a function or source line number

For detailed command syntax, see Command Reference.

2. Script Mode

Press Enter to enter script mode and start writing GhostScope scripts to probe processes:

  • Use print to output local variables, parameters, and even global variables
  • As long as DWARF info contains variable descriptions, you can get meaningful data
  • Support for script variables and simple conditional logic
  • For more script syntax details, see Script Language Reference

Script Mode Script editing mode

After writing, press Ctrl+S to submit code. If all goes well, the script will be compiled to eBPF bytecode and loaded onto the uprobe.

Script Result Script execution result

3. Command Mode

At this point, if everything works, we'll see the script output in the eBPF output panel. But to view it, we need to switch focus to the eBPF output panel. eBPF Output eBPF output results

Press Esc to switch from input mode to command mode. In this mode:

  • Vim-style navigation: Use hjkl to browse history (inspired by cgdb)
  • Return to input mode: Press i
  • Panel switching:
    • Tab / Shift+Tab: Switch between panels
    • Ctrl+W + hjkl: Vim-style panel jumping (a blessing for Vim lovers 😁)

Panel Operation Tips

eBPF Output Panel

When focused on the eBPF output panel, it also supports Vim-style navigation and quick movement.

Fullscreen Mode

If panels are too small, besides setting ratios at startup, you can:

  • Press Ctrl+W z: Fullscreen the current focused panel (learned from tmux, also my favorite 😉)

For more panel operations, see TUI Reference Guide and Command Reference.

💡 Recommended Workflow

A more efficient approach is to start from the source panel:

  1. Browse source: Switch focus to the source panel, use Vim-style navigation to browse code
  2. Switch files: Press o to bring up the file search bar, quickly find and switch to other source files
  3. Quick trace point setting: When you see an interesting line, press Space to directly enter script mode
    • The trace target automatically sets to the file and line number at the cursor
    • This design is inspired by cgdb, I really love this shortcut

This workflow is more fluid, making trace point setting effortless.

💡 Viewing Available Variables at Trace Points

Before setting a trace point, if you want to know which local variables and parameters are accessible at a specific location, you can use the info commands:

info line <file:line>       # View available variables at a source line
info function <func_name>   # View available variables at function entry
info address <0xADDR>       # View available variables at an address

These commands display debug information for that location, including the list of accessible variables:

Info Source Line Using info line command to view available variables

Using Script Files

For repeated use, save your traces in a file:

# trace.gs
trace calculate_something {
    print "FUNC: a={} b={}", a, b;
}

trace sample_program.c:16 {
    print "LINE16: result={}", result;
}

Run it:

sudo ghostscope -p $(pidof your_app) --script-file trace.gs

You can also load it directly from the TUI’s command panel using source <filename>:

Source Trace File Use the source command to load a script file directly

💡 Tip: After setting multiple trace points in the TUI, you can use the save trace <filename> command to save all current trace points to a file for later reuse. See Command Reference for details.

Next Steps

  • Limitations (Recommended): Read Limitations to understand known constraints and best practices
  • Technical background: I don't really want to say so much, but I have to 😂. Understanding uprobe mechanism is crucial for using GhostScope correctly. I recommend reading the Uprobe Internals documentation to avoid common pitfalls.
  • Full TUI Reference: See TUI Reference Guide for all keyboard shortcuts
  • Command Reference: See Command Reference for all available commands
  • Script Language: Learn the full syntax in Script Language Reference
  • Configuration: See Configuration Reference for customization options