LOGGING_GUIDE.md

Logging Guide for IMO Math Problem Solver

Comprehensive logging has been added to help you debug and monitor the application, especially in containerized environments like Hugging Face Spaces.

📋 Logging Overview

The Gradio app now includes detailed logging at every step:

• API key detection
• Request validation
• Subprocess execution
• File operations
• Solution checking
• Error handling

🔍 What Gets Logged

Startup Logging

2025-11-26 10:30:00 [INFO] __main__: Starting IMO Math Problem Solver - Gradio Interface
2025-11-26 10:30:00 [INFO] __main__: Python version: 3.10.12
2025-11-26 10:30:00 [INFO] __main__: Gradio version: 3.50.0
2025-11-26 10:30:00 [INFO] __main__: Working directory: /app
2025-11-26 10:30:00 [INFO] __main__: ============================================================
2025-11-26 10:30:00 [INFO] __main__: Checking API keys availability...
2025-11-26 10:30:00 [INFO] __main__: ✓ GOOGLE_API_KEY found (length: 39)
2025-11-26 10:30:00 [INFO] __main__: Available providers: ['Google Gemini 2.5 Pro']

Request Logging

2025-11-26 10:31:15 [INFO] __main__: ============================================================
2025-11-26 10:31:15 [INFO] __main__: NEW SOLVE REQUEST
2025-11-26 10:31:15 [INFO] __main__: ============================================================
2025-11-26 10:31:15 [INFO] __main__: Provider: Google Gemini 2.5 Pro
2025-11-26 10:31:15 [INFO] __main__: Max runs: 10
2025-11-26 10:31:15 [INFO] __main__: Num agents: 1
2025-11-26 10:31:15 [INFO] __main__: Other prompts: None
2025-11-26 10:31:15 [INFO] __main__: Problem length: 245 characters

Subprocess Logging

2025-11-26 10:31:15 [INFO] __main__: Starting SINGLE AGENT mode
2025-11-26 10:31:15 [INFO] __main__: Agent file: code/agent.py
2025-11-26 10:31:15 [INFO] __main__: Solution log file: logs/session_1732630275/solution.log
2025-11-26 10:31:15 [INFO] __main__: Command: python code/agent.py /tmp/tmpxyz.txt --log logs/session_1732630275/solution.log --max_runs 10
2025-11-26 10:31:15 [INFO] __main__: Starting subprocess...
2025-11-26 10:31:16 [INFO] __main__: Subprocess started with PID: 12345

Progress Logging

2025-11-26 10:31:20 [INFO] __main__: Processed 50 lines from subprocess
2025-11-26 10:31:25 [INFO] __main__: Processed 100 lines from subprocess
2025-11-26 10:31:30 [INFO] __main__: Processed 150 lines from subprocess

Completion Logging

2025-11-26 10:35:42 [INFO] __main__: Subprocess completed with return code: 0
2025-11-26 10:35:42 [INFO] __main__: Total output lines: 523
2025-11-26 10:35:42 [INFO] __main__: Checking for solution in log file...
2025-11-26 10:35:42 [INFO] __main__: Log file size: 45678 bytes
2025-11-26 10:35:42 [INFO] __main__: ✓ SOLUTION FOUND in log file!
2025-11-26 10:35:42 [INFO] __main__: Returning SUCCESS result to user
2025-11-26 10:35:42 [INFO] __main__: Cleaned up temporary problem file: /tmp/tmpxyz.txt
2025-11-26 10:35:42 [INFO] __main__: ============================================================
2025-11-26 10:35:42 [INFO] __main__: SOLVE REQUEST COMPLETED
2025-11-26 10:35:42 [INFO] __main__: ============================================================

Error Logging

2025-11-26 10:31:15 [ERROR] __main__: API key not found for OpenAI GPT-5
2025-11-26 10:31:15 [ERROR] __main__: Available providers: ['Google Gemini 2.5 Pro']

📍 Viewing Logs

On Hugging Face Spaces

1. Go to your Space
2. Click "Logs" tab (top navigation)
3. View real-time logs

The logs will show all the information logged by the application.

Locally

When running locally, logs appear in two places:

1. Console Output

All logs print to stdout/stderr:

python gradio_app.py

2. Redirect to File (Optional)

To save logs to a file:

python gradio_app.py 2>&1 | tee app.log

This will display logs in console AND save to app.log.

🔧 Log Levels

The app uses standard Python logging levels:

Level	When Used	Example
INFO	Normal operations	"Subprocess started with PID: 12345"
WARNING	Potential issues	"No API keys found at startup!"
ERROR	Errors that can be handled	"API key not found for OpenAI GPT-5"
EXCEPTION	Unhandled exceptions	Full stack trace with logger.exception()

🐛 Debugging with Logs

Problem: App won't start

Look for:

[ERROR] __main__: Failed to start subprocess
[EXCEPTION] __main__: EXCEPTION occurred during solve_problem

Check:

• API keys are set correctly
• code/ directory exists
• Agent files are present

Problem: No solution found

Look for:

[INFO] __main__: Subprocess completed with return code: 1
[WARNING] __main__: No solution found in log file

Check:

• The subprocess return code (0 = success, non-zero = error)
• Review agent-specific logs in logs/session_*/solution.log

Problem: API key issues

Look for:

[WARNING] ✗ GOOGLE_API_KEY not found
[ERROR] __main__: API key not found for Google Gemini 2.5 Pro

Fix:

• Set API key in Hugging Face Spaces: Settings → Repository Secrets
• Restart the Space (Factory reboot)

Problem: Subprocess fails

Look for:

[ERROR] __main__: Failed to start subprocess: <error message>
[INFO] __main__: Command: python code/agent.py ...

Check:

• The exact command that was run
• Whether agent file exists
• Python interpreter is available

📊 Log Analysis Examples

Example 1: Successful Run

2025-11-26 10:30:00 [INFO] __main__: NEW SOLVE REQUEST
2025-11-26 10:30:00 [INFO] __main__: Provider: Google Gemini 2.5 Pro
2025-11-26 10:30:00 [INFO] __main__: Created temporary problem file: /tmp/tmpxyz.txt
2025-11-26 10:30:00 [INFO] __main__: Starting SINGLE AGENT mode
2025-11-26 10:30:00 [INFO] __main__: Subprocess started with PID: 12345
2025-11-26 10:30:50 [INFO] __main__: Subprocess completed with return code: 0
2025-11-26 10:30:50 [INFO] __main__: ✓ SOLUTION FOUND in log file!
2025-11-26 10:30:50 [INFO] __main__: SOLVE REQUEST COMPLETED

✅ Result: Success! Everything worked.

Example 2: Missing API Key

2025-11-26 10:30:00 [INFO] __main__: ✗ GOOGLE_API_KEY not found
2025-11-26 10:30:05 [ERROR] __main__: API key not found for Google Gemini 2.5 Pro
2025-11-26 10:30:05 [ERROR] __main__: Available providers: []

❌ Problem: No API key set. Fix: Add GOOGLE_API_KEY to secrets.

Example 3: Agent Subprocess Error

2025-11-26 10:30:00 [INFO] __main__: Command: python code/agent.py /tmp/tmpxyz.txt ...
2025-11-26 10:30:00 [INFO] __main__: Subprocess started with PID: 12345
2025-11-26 10:30:10 [INFO] __main__: Subprocess completed with return code: 1
2025-11-26 10:30:10 [WARNING] __main__: No solution found in log file

⚠️ Problem: Agent ran but failed. Check: Look at logs/session_*/solution.log for agent-specific errors.

🎯 Key Metrics to Monitor

Track these in your logs:

1. Return codes: return code: 0 = success
2. Processing time: Time between "Subprocess started" and "completed"
3. Output volume: "Total output lines" indicates activity
4. Success rate: Ratio of "SOLUTION FOUND" to total requests

📝 Custom Logging (Advanced)

If you want more detailed logging, edit gradio_app.py:

Change Log Level

# More verbose logging
logging.basicConfig(
    level=logging.DEBUG,  # Changed from INFO
    format='%(asctime)s [%(levelname)s] %(name)s: %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)

Add Custom Logs

logger.debug("Detailed debug information")
logger.info("General information")
logger.warning("Warning message")
logger.error("Error message")
logger.exception("Exception with full stack trace")

🔐 Security Note

⚠️ Never log API keys!

The current logging shows:

✓ GOOGLE_API_KEY found (length: 39)  # ✅ Safe - only shows length

NOT:

✓ GOOGLE_API_KEY = AIza...xyz  # ❌ NEVER DO THIS

📦 Log Retention

Hugging Face Spaces

• Logs are available in the "Logs" tab
• Older logs scroll out of view
• Not permanently stored (restart clears logs)

Local Development

• Console logs disappear when app stops
• Use tee to save to file if needed
• Agent logs saved in logs/session_*/*.log directories

🚀 Production Tips

1. Monitor startup: Check logs immediately after deployment
2. Watch for patterns: Recurring errors indicate systematic issues
3. Check timestamps: Long gaps between log entries = slow operations
4. Review after changes: Always check logs after updating code
5. Save critical runs: Copy important logs before they're lost

📖 Related Files

• gradio_app.py - Main file with logging
• app.py - Copy for Hugging Face (same logging)
• logs/session_*/*.log - Agent-specific logs

---

With comprehensive logging, you can now see exactly what's happening in your containerized environment! 🎉