Debugging

Debugging Guide

This guide covers debugging techniques for Ripple development, including IDE setup, logging configuration, and troubleshooting strategies.

IDE Debugging Setup

VS Code with LLDB

1. Prerequisites

   • Install CodeLLDB extension
   • Configure launch.json (if not already present)

2. Basic Debug Configuration

   {
     "version": "0.2.0",
     "configurations": [
       {
         "type": "lldb",
         "request": "launch",
         "name": "Debug Ripple",
         "cargo": {
           "args": ["build"],
           "filter": {
             "name": "ripple",
             "kind": "bin"
           }
         },
         "args": [],
         "cwd": "${workspaceFolder}"
       }
     ]
   }

3. Starting a Debug Session

   • Open core/main/main.rs
   • Set breakpoints by clicking the gutter or pressing F9
   • Press F5 or click Debug → Start Debugging

4. Debug Features

   • Step Through (F11)
   • Step Over (F10)
   • Step Out (Shift+F11)
   • Continue (F5)
   • Variables and Watch windows
   • Call Stack view
   • Breakpoint conditions

Logging and Diagnostics

Log Levels

Ripple uses the following log levels:

• ERROR: Failures requiring immediate attention
• WARN: Potential issues or unexpected states
• INFO: Important state changes
• DEBUG: Detailed information for development
• TRACE: Fine-grained execution flow

Configuring Log Output

1. Environment Variables

   # Set log level for all components
   export RUST_LOG=debug
   
   # Component-specific logging
   export RUST_LOG=ripple=debug,broker=trace

2. Log File Output

   # Log to file
   ripple run <device-ip> 2> ripple.log
   
   # Log to both console and file
   ripple run <device-ip> 2>&1 | tee ripple.log

Common Debugging Scenarios

Extension Loading Issues

1. Check extension paths in manifest
2. Verify library file permissions
3. Monitor debug logs for loading sequence
4. Set breakpoints in extension initialization

Broker Communication

1. Enable TRACE logging for broker components
2. Monitor WebSocket traffic
3. Verify message routing in EndpointBroker
4. Check Thunder broker connections

Rule Processing

1. Set log level to DEBUG for rule evaluation
2. Inspect JQ rule inputs and outputs
3. Use breakpoints in rule application logic
4. Verify rule file paths and content

Best Practices

1. Workspace Setup

   • Start Ripple from VS Code for consistent paths
   • Use workspace-relative paths in configurations
   • Keep debug symbols in development builds

2. Efficient Debugging

   • Use conditional breakpoints for specific cases
   • Leverage watch expressions for complex conditions
   • Set function breakpoints for event handlers
   • Use logpoints for non-breaking trace output

3. Log Management

   • Rotate log files to manage size
   • Use structured logging for easier parsing
   • Include context in log messages
   • Clean up old log files regularly

Troubleshooting Guide

Common Issues

1. Missing Symbols

   • Ensure debug symbols are enabled in Cargo.toml
   • Verify correct build profile is used
   • Check LLDB path configuration

2. Path-Related Errors

   • Launch from workspace root
   • Check manifest paths
   • Verify extension locations

3. Connection Issues

   • Check device network connectivity
   • Verify WebSocket endpoints
   • Monitor connection logs

Debug Performance

1. Build Optimization

   • Use debug builds for development
   • Enable incremental compilation
   • Configure appropriate optimization levels

2. Tool Performance

   • Limit breakpoint count
   • Use conditional breakpoints judiciously
   • Profile debug sessions

Additional Resources

• VS Code Debugging Documentation
• LLDB Tutorial
• Architecture for component relationships
• Testing for integration with test frameworks