Skip to content

Debugging Scripts

When writing complex bpftrace scripts, errors can arise from syntax issues, incorrect probe definitions, or type mismatches in eBPF programs. Debugging these requires leveraging verbose logging, type-checking, and validation tools provided by bpftrace. This section covers techniques to identify and resolve script errors effectively.

Verbose Logging

The -v (verbose) flag enables detailed logging during script execution, revealing internal processing steps, probe resolution, and potential issues. Use it to diagnose problems like missing probes, incorrect kernel versions, or unresolved symbols.

Example: 

bpftrace -v script.bt

Output example: 

INFO: bpftrace v0.14.0
INFO: Loading script.bt
INFO: Found 3 probes in script.bt
INFO: Could not resolve probe: kprobe:sys_open
ERROR: No such probe: kprobe:sys_open

If a probe is unresolved, verify its name using bpftrace --list-probes or check kernel version compatibility.

Log Level Control

The --log-level parameter allows fine-grained control over the verbosity of logs. Valid levels include: - 0 (quiet): Minimal output - 1 (info): Standard informational messages - 2 (debug): Detailed debug logs - 3 (trace): Full trace of internal operations

Use this to adjust logging granularity without disabling all verbose output. For example: 

bpftrace --log-level 2 script.bt

Type-Checking

eBPF programs require strict type-checking due to their safety constraints. Use the --type-check flag to validate scripts before execution, catching errors like invalid variable types or incorrect arithmetic operations.

Example: 

bpftrace --type-check script.bt

Error example: 

ERROR: type mismatch: 'string' used in arithmetic operation

This indicates a script attempting to perform math with a string variable. Fix by ensuring variables are of numeric type.

Pass Mode

The --pass flag runs the script in "pass mode," validating syntax and probe existence without executing the eBPF program. This is ideal for pre-flight checks.

Example: 

bpftrace --pass script.bt

Success output: 

PASS: script.bt has 3 probes, 0 errors

Failure output: 

ERROR: syntax error: unexpected '}', expecting ';'

Use this to catch syntax errors early, such as missing semicolons or mismatched braces.

Common Pitfalls

  • Kernel version mismatches: Ensure the kernel supports the required eBPF features (e.g., CONFIG_BPF_SYSCALL). Use uname -r and check kernel documentation.
  • Probe syntax errors: Probes like kprobe:__x64_sys_open require precise syntax. Use bpftrace --list-probes to verify valid names.
  • Resource limits: Some scripts may fail due to insufficient memory or CPU limits. Monitor with dmesg or perf.

Key takeaways

  • Use -v and --log-level to inspect detailed runtime logs and resolve probe resolution issues.
  • Leverage --type-check to catch eBPF type mismatches and invalid operations.
  • Run scripts in --pass mode to validate syntax and probe existence without execution.
  • Combine logging and type-checking to isolate errors in complex scripts.