Logs & Diagnostics

Logging Overview

Tag-AI includes a comprehensive logging system that records application activities, errors, and diagnostic information. These logs are invaluable for troubleshooting issues and understanding what's happening behind the scenes.

The logging system is organized by component, with separate log files for different parts of the application. This makes it easier to track down specific issues.

Log File Locations

Log files are stored in platform-specific locations:

Windows

%LOCALAPPDATA%\Tag-AI\Logs\

Example: C:\Users\Username\AppData\Local\Tag-AI\Logs\

macOS

~/Library/Logs/Tag-AI/

Example: /Users/Username/Library/Logs/Tag-AI/

Linux

~/.local/state/Tag-AI/logs/

Example: /home/username/.local/state/Tag-AI/logs/

Log Types and Contents

Tag-AI creates several different log files:

Main Application Log

app.log - Contains general application events, startup information, and high-level operations.

Component-Specific Logs

• main.log - Main window and application lifecycle events
• setup.log - Setup wizard operations and installation steps
• photo_ollama.log - Local image processing with LLaVA
• photo_gemini.log - Cloud image processing with Gemini API
• scan_window.log - Scan interface operations
• purge_window.log - Purge missing files utility operations
• paths.log - File and directory path resolution information

Timestamped Scan Logs

For each scanning session, a timestamped log is created:

scanner_YYYYMMDD_HHMMSS.log

Example: scanner_20240314_153042.log

These logs contain detailed information about a specific scanning session, making it easier to track down issues with particular scans.

Reading and Interpreting Logs

Tag-AI log files use a standard format for each entry:

YYYY-MM-DD HH:MM:SS - LEVEL - MODULE - FUNCTION - MESSAGE

For example:

2024-03-14 15:30:42 - INFO - photo_ollama - process_file_worker - Processing image: C:\Photos\vacation.jpg

Log Levels

Tag-AI uses standard logging levels to indicate the importance of messages:

• DEBUG - Detailed information for diagnosing problems
• INFO - Confirmation that things are working as expected
• WARNING - Indication that something unexpected happened, but the application can continue
• ERROR - Due to a more serious problem, the application couldn't perform some function
• CRITICAL - A serious error indicating the application may be unable to continue running

Common Log Patterns

Successful Operations

Look for entries with "success" or "completed" and INFO level:

2024-03-14 15:30:45 - INFO - photo_ollama - insert_data_into_db - ✅ Inserted data for C:\Photos\sunset.jpg

Warnings

Warnings indicate non-critical issues that might need attention:

2024-03-14 15:31:02 - WARNING - photo_ollama - process_image_resized - ⚠️ Image too large, resizing to target size

Errors

Error entries indicate failures that prevented some operation:

2024-03-14 15:32:17 - ERROR - photo_ollama - calculate_file_hash - ❌ Error calculating hash for C:\Photos\corrupted.jpg: [Errno 13] Permission denied

Using Logs for Troubleshooting

Installation Issues

Check setup.log for detailed information about each step of the setup process. Look for ERROR level entries indicating what might have failed.

Scanning Problems

For scan issues, examine the timestamped scanner logs and photo_ollama.log or photo_gemini.log depending on your configuration. Key things to look for:

• Connection errors to Ollama or Gemini API
• File access permission issues
• Memory errors
• Unexpected terminations

Database Issues

Database problems are typically logged with specific SQLite error codes. Common patterns:

• "database is locked" - Another process has the database locked
• "no such table" - Database schema issue or corruption
• "disk I/O error" - Storage device problems
• "database disk image is malformed" - Database corruption

API and Network Issues

When using Gemini API, check for:

• API key validation errors
• Rate limiting messages
• Network timeout errors
• Response parsing issues

GPU Acceleration Problems

For GPU-related issues, look for:

• CUDA or ROCm detection entries
• "GPU utilization" messages
• "Out of memory" errors
• Driver version compatibility notes

Log Management

Log Rotation

Tag-AI automatically manages log files to prevent them from growing too large:

• Component logs are appended to until they reach a size limit
• Scan logs are created new for each session with timestamps
• Old scan logs are automatically purged based on the retention setting

Log Retention

By default, Tag-AI keeps logs for 24 hours before deleting them. You can modify this in the configuration:

1. Open the Configuration Editor (Actions → Edit Config)
2. Add or modify the log_retention_hours value in the [settings] section
3. Save the configuration

Clearing Logs

If needed, you can manually clear logs:

1. Close Tag-AI
2. Navigate to the log directory for your platform
3. Delete any log files you wish to remove
4. Restart Tag-AI

Additional Diagnostic Tools

Unable to Do File

Tag-AI creates a file named unable_to_do.txt in its installation directory that lists images it couldn't process. This file includes the full paths of problematic files for your reference.

Database Inspection

For advanced users, directly examining the database can provide insights into issues. You can use tools like DB Browser for SQLite to open and inspect the database file. See Database Management for details.

Console Output

When running Tag-AI from a terminal or command prompt, additional diagnostic information is printed to the console. This can be captured by redirecting output:

# Windows
tag-ai.exe > console_output.txt 2>&1

# macOS/Linux
./tag-ai > console_output.txt 2>&1

Ollama Logs

For issues with local processing, Ollama maintains its own logs at:

• Windows: %LOCALAPPDATA%\ollama\logs
• macOS/Linux: ~/.ollama/logs

Diagnostic Data for Support

When contacting support about an issue, include:

1. Relevant log files
2. Screenshots of any error messages
3. Your system specifications (OS, GPU, RAM)
4. Steps to reproduce the issue
5. Tag-AI version number