Monitoring & Logs
Monitor execution, analyze logs, and debug automation issues
Overview
Qontinui Runner provides comprehensive logging and monitoring capabilities to help you understand what your automation is doing, diagnose issues, and optimize performance.
Three Types of Logs: Runner maintains separate logs for general execution (info, warnings, errors), image recognition results, and action execution details.
Log File Locations
In development mode, logs are stored in the .dev-logs/ directory at the project root. In production, logs are stored in your system's application data directory.
runner-frontend.log
Vite/React dev server output, HMR updates, and frontend console logs
.dev-logs/runner-frontend.logrunner-backend.log
Rust/Cargo build output, tracing logs, and Python stderr
.dev-logs/runner-backend.logrunner-rust-logs/
Detailed Rust tracing logs (junction to AppData)
.dev-logs/runner-rust-logs/qontinui-lib.log
Python library logs: web extraction, vision, and state detection
.dev-logs/qontinui-lib.logai-output.jsonl
AI chat logs in JSONL format (prompts and responses)
.dev-logs/ai-output.jsonlProduction Log Locations
- Windows:
%LOCALAPPDATA%\qontinui-runner\logs\ - macOS:
~/Library/Application Support/qontinui-runner/logs/ - Linux:
~/.local/share/qontinui-runner/logs/
Log Levels
Logs are categorized by severity level. You can filter logs by level in the Runner UI or when viewing log files.
Detailed diagnostic information for debugging
Examples:
- Python executor message parsing
- Image recognition scores and coordinates
- Internal state transitions
Normal execution information and progress updates
Examples:
- Workflow started/completed
- Actions executed successfully
- Configuration loaded
Warning conditions that don't prevent execution
Examples:
- Image recognition below threshold
- Retry attempts for failed actions
- Health check timeouts
Error conditions that cause failures
Examples:
- Python process crashed
- Image not found on screen
- Configuration validation failed
Adjusting Log Levels: Set the RUST_LOG environment variable to control log verbosity.
RUST_LOG=qontinui_runner=debug,tauri=infoReal-Time Monitoring
Monitor automation execution in real-time through the Runner UI's Logs tab, which provides three specialized log views.
General Logs
View all execution events, errors, and system messages in real-time
- Filter by log level (Debug, Info, Warn, Error)
- Search logs by keyword
- Auto-scroll to follow execution
- Copy logs to clipboard for sharing
- Color-coded by severity
Image Recognition Logs
Track image matching results with similarity scores and coordinates
- Similarity scores for each match attempt
- Screen coordinates where images were found
- Multi-scale search results
- Match confidence levels
- Performance metrics (search time)
Action Logs
Hierarchical view of workflow execution with action details
- Tree structure showing workflow → action hierarchy
- Action status (success, failed, pending)
- Execution timestamps and duration
- Action parameters and results
- Expand/collapse for detailed inspection
Health Monitoring
Runner includes an automatic health monitoring system that tracks the Python executor's responsiveness.
Ping/Pong Health Checks
Every 5 seconds, Runner sends a ping to the Python executor
- •Pong response expected within 3 seconds
- •After 3 consecutive failures, executor marked as unhealthy
- •Health status visible in UI status indicator
Process Monitoring
Runner monitors the Python subprocess for unexpected termination
- •Detects if Python process crashes or exits
- •Logs stdout/stderr closure events
- •Emits error events to frontend for user notification
Performance Tracking
Measures response latency for health checks
- •Ping-pong latency logged at DEBUG level
- •Helps identify performance degradation
- •Useful for diagnosing slow automation execution
Viewing Logs
In Runner UI (Recommended)
Use the built-in Logs tab for real-time monitoring with filtering and search
Click the "Logs" tab in RunnerSelect log type: General, Image Recognition, or ActionsUse filters to narrow down by level or keywordClick actions for detailed informationVia Command Line
Tail log files directly for development and debugging
Windows PowerShell: Get-Content .dev-logs\runner-backend.log -Tail 100 -WaitmacOS/Linux: tail -f .dev-logs/runner-backend.logSearch for errors: Select-String -Path .dev-logs\runner-backend.log -Pattern "error" -CaseSensitive:$falseIn Text Editor
Open log files in your preferred text editor for analysis
Navigate to .dev-logs/ directoryOpen runner-backend.log or runner-frontend.logSearch for timestamps or error patternsUse syntax highlighting for JSONL filesDebugging Tips
Check logs immediately after errors
The most recent logs contain crucial context about what went wrong. Look for ERROR or WARN level messages immediately before the failure.
Use log levels strategically
Start with ERROR level to find failures, then switch to WARN or INFO to see context. Use DEBUG only when you need detailed execution traces.
Search for specific patterns
Look for keywords like "failed", "timeout", "not found", "exception", or action names. This quickly narrows down the problem area.
Compare successful vs failed runs
If an automation works sometimes and fails other times, compare logs from both scenarios to identify what's different.
Check image recognition scores
Low similarity scores (< 0.8) in Image Logs indicate images aren't matching well. This often means UI changed or image needs recapture.
Monitor health check failures
Consecutive ping timeout warnings indicate the Python executor is overloaded or stuck. This can cause overall automation slowness.
Review AI chat logs for context
The ai-output.jsonl file contains all AI interactions. This is useful for understanding what the AI agent was trying to do during AI_PROMPT actions.
Performance Monitoring
Use logs to identify performance bottlenecks and optimize automation execution speed.
Action Duration
Action logs include execution timestamps
How to use: Compare start and end times to find slow actions. Common culprits: WAIT actions, slow API calls, complex image searches.
Image Search Time
Image recognition logs show search duration
How to use: Multi-scale searches take longer. Use search regions to limit area and speed up matching.
Health Check Latency
Ping-pong latency indicates executor responsiveness
How to use: Rising latency over time suggests memory leaks or resource exhaustion. Restart executor if latency exceeds 500ms.
Screenshot Capture Time
Logged when screenshots are captured
How to use: Slow capture (>100ms) can indicate display driver issues or high system load.
Log Management
Clearing Logs
Logs can be cleared from the Runner UI or by deleting log files
- •UI: Click 'Clear Logs' button in Logs tab
- •Manual: Delete files from .dev-logs/ directory
- •AI output: Clear with clear_ai_output_log() Rust command
Log Rotation
Production logs rotate daily to prevent excessive disk usage
- •Daily rotation: qontinui-runner.log becomes qontinui-runner.log.YYYY-MM-DD
- •Old logs deleted automatically after 30 days
- •Development logs (.dev-logs/) are not rotated
Exporting Logs
Share logs for troubleshooting or bug reports
- •Copy from UI: Use 'Copy Logs' button
- •Export file: Zip entire .dev-logs/ directory
- •Include: Workflow config JSON for full context
Common Log Patterns
Image not found on screenMeaning: The image recognition failed to locate the target image
Solutions:
- •Check if the UI element is actually visible
- •Lower similarity threshold (try 0.8 instead of 0.9)
- •Recapture the image if UI has changed
- •Verify the correct monitor is being searched
Pong timeout: no response for X secondsMeaning: Python executor is not responding to health checks
Solutions:
- •Executor may be stuck in a long-running operation
- •Check for infinite loops in workflow logic
- •Increase timeout if operations are legitimately slow
- •Restart Runner if timeouts persist
Failed to parse executor messageMeaning: Rust couldn't parse JSON from Python stdout
Solutions:
- •Check for Python print statements (use stderr instead)
- •Verify Python is outputting valid JSON
- •Look for stack traces mixed with JSON output
- •Update qontinui library if format changed
Python process stdout closed unexpectedlyMeaning: Python executor terminated without clean shutdown
Solutions:
- •Check Python logs for exceptions or errors
- •Verify Python dependencies are installed
- •Look for segmentation faults or crashes
- •Check for uncaught exceptions in workflow code
Best Practices
Keep logs open during development
Always have the Logs tab visible when testing new workflows. This lets you see errors immediately and understand execution flow.
Use INFO level for production
DEBUG level generates excessive output and can slow execution. INFO level provides sufficient detail for most scenarios.
Review logs after every automation run
Even successful runs may have warnings that indicate potential issues. Check for retry attempts or low similarity scores.
Archive logs for debugging sessions
Before troubleshooting, copy the entire .dev-logs/ directory. This preserves the exact state for analysis.
Search before scrolling
Don't scroll through thousands of log lines. Use search functionality to find relevant entries quickly.
Correlate logs with screenshots
When debugging, review screenshots alongside logs. Screenshots show what the automation saw, logs show what it decided to do.