Colog

A Visual Studio Code extension for intelligent iOS device log filtering and monitoring with colorized terminal output.

Features

Core Functionality

• iOS Device Log Monitoring: Direct integration with idevicesyslog for real-time log capture
• Smart Process Filtering: Filter by app process name with automatic detection and persistence
• Dual Filtering Modes: Text matching (case-insensitive) and regex patterns with interactive toggle

Advanced Filtering

• Framework Separation: Automatically shows only app logs, filters out system frameworks (UIKitCore, etc.)
• Multi-line Log Handling: Intelligently preserves log entry structure across continuation lines
• Header Control: Toggle display of timestamps and process information (showHeader setting)

Integration & User Experience

• Debug Session Auto-start: Automatically opens log monitoring when debugging starts
• Editor Integration: Filter logs using selected text directly from code editor
• Smart Terminal Management: Reuses existing terminals, hot-reloads on configuration changes
• Context Menus: Right-click integration in terminals and editors
• Device Persistence: Remembers selected device per workspace
• Keyboard Shortcuts: Quick access via Cmd+Shift+F F (press F twice)

Prerequisites

• libimobiledevice: Install via Homebrew on macOS

  brew install libimobiledevice
  

• Python 3.x: Required for log processing
• Connected iOS Device: Must be trusted and connected via USB

Usage

Main Log Filtering

1. Launch Filter Dialog

   • Use keyboard shortcut: Cmd+Shift+F F (press F twice)
   • Or use Command Palette: "Colog: Filter iOS Logs"

2. Configure Process

   • Enter iOS app process name
   • Setting is automatically saved for future use

3. Enter Filter Text

   • Type text or regex pattern to filter logs
   • Press Tab to toggle between text matching and regex modes
   • Visual indicator shows current mode in dialog title

4. Multi-Device Selection (if multiple devices connected)

   • Shows device name, iOS version, and device type
   • Selection is remembered per workspace

Filter from Text Selection

1. Select Text in any editor
2. Right-click → "Filter Logs for Selected Text"
3. Configure Process (if not already set)
4. Choose Device (if multiple connected)
5. Filtering starts automatically using selected text

Device Management

1. Manual Device Selection

   • Command Palette: "Colog: Select iOS Device"

2. Device Information

   • View device name, iOS version, device type
   • Copy device ID to clipboard
   • See connection status

Debug Session Integration

1. Configure Process Name

   {
     "colog.processName": "YourAppName"
   }
   

2. Start Debugging (F5 or Debug button)

3. Log Terminal Opens Automatically

   • Shows logs for configured process
   • Stops automatically when debugging ends
   • Can be disabled via colog.autoOpenOnDebug setting

Configuration

Available Settings

Configuration Examples

{
  "colog.processName": "MyiOSApp",
  "colog.autoOpenOnDebug": true,
  "colog.showHeader": false,
  "colog.showAllLogs": true
}

Commands Reference

Advanced Features

Framework Filtering

• Automatic System Log Filtering: Excludes logs from system frameworks like UIKitCore, FrontBoardServices, CoreFoundation
• Business Logic Focus: Shows only your app's logs and relevant system messages
• Configurable: Controlled by the underlying Python processing engine

Multi-line Log Support

• Structure Preservation: Maintains log entry boundaries across multiple lines
• Context Awareness: Filters entire log entries, not just individual lines
• Continuation Lines: Properly handles logs that span multiple terminal lines

Terminal Management

• Smart Reuse: Reuses existing terminals with the same filter configuration
• Hot Reload: Automatically restarts terminals when settings change
• Process Control: Proper handling of Ctrl+C to stop log monitoring
• Multiple Sessions: Support for concurrent filtering with different parameters

Examples

Basic Text Filtering

# Generated command for process "MyApp" with filter "error"
idevicesyslog --process MyApp | python3 ioslog.py --process_name "MyApp" --filter "error"

Regex Pattern Filtering

# Filter for specific log patterns
# Pattern: HTTP status codes (4xx, 5xx errors)
idevicesyslog --process MyApp | python3 ioslog.py --process_name "MyApp" --filter "HTTP.*[45]\d\d" --regex

Multi-Device Scenario

1. Connect multiple iOS devices
2. Run filter command
3. Select target device from list:

   📱 Alice's iPhone (iOS 17.1) - iPhone 15 Pro
   📱 Test Device (iOS 16.5) - iPhone 12
   

4. Device selection saved per workspace

Header Control Example

With colog.showHeader: true:

2024-01-15 10:30:45.123 MyApp[1234] <Notice>: User logged in successfully

With colog.showHeader: false:

User logged in successfully

Troubleshooting

Device Issues

• No devices found: Ensure device is connected via USB and trusted in iOS Settings
• Multiple devices detected: Use "Colog: Select iOS Device" command to choose specific device
• Device switching: Extension automatically restarts all terminals when device changes
• Connection lost: Reconnect device and restart filter terminals

Filtering Issues

• No logs appear:
  • Verify process name matches exactly (case-sensitive)
  • Try filtering without process name first to see all logs
  • Check if app is actually running and generating logs
• System logs showing: Business logs are automatically separated from system frameworks
• Regex not working: Ensure "Regular expression matching" mode is selected (Tab to toggle)
• Multi-line logs truncated: Extension preserves log structure automatically

Performance Issues

• Too many logs: Use more specific process names or filter patterns
• Terminal slowdown: Restart terminals or use more restrictive filters
• Memory usage: Close unused filter terminals to free resources

Development

Building and Testing

# Install dependencies
npm install

# Compile TypeScript and copy Python files
npm run compile

# Run tests
npm test

# Lint and format code
npm run lint
npm run format

# Debug extension
# Press F5 to open Extension Development Host

Architecture

• TypeScript Extension Layer: VSCode integration, UI, and command handling
• Python Processing Core: ioslog.py handles vis-decoding, filtering, and colorization
• Dual-Language Design: TypeScript for VSCode API, Python for iOS log processing

License

MIT