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:
```bash
python gradio_app.py
```

#### 2. Redirect to File (Optional)
To save logs to a file:
```bash
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

```python
# 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

```python
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](gradio_app.py)** - Main file with logging
- **[app.py](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! 🎉