Ambient Flare
Home/Docs/Logs & Diagnostics

Logs & Diagnostics

On this page#

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.

Tag-AI Logging System Overview

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/

If Tag-AI can't write to these standard locations, it may fall back to using a temporary directory. This is noted in the console output when the application starts.

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#

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:

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:

Database Issues#

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

API and Network Issues#

When using Gemini API, check for:

GPU Acceleration Problems#

For GPU-related issues, look for:

Log Management#

Log Rotation#

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

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

Always close Tag-AI before manually deleting log files to avoid potential file lock issues.

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:

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