# Logging and Monitoring - Quick Reference Guide

## Overview

This guide provides a quick reference for the logging and monitoring features of the Survey Custom Certificate Template module.

## Log Levels

| Level | Usage | Example |
|-------|-------|---------|
| **DEBUG** | Detailed diagnostic information | Data retrieval details, placeholder counts |
| **INFO** | General informational messages | Certificate generation start/success, template operations |
| **WARNING** | Warning messages for non-critical issues | Missing data, validation warnings |
| **ERROR** | Error messages for failures | Certificate generation failures, conversion errors |
| **CRITICAL** | Critical system issues | LibreOffice unavailability |

## Key Log Patterns

### Certificate Generation Logs

```
# Generation Start
INFO: === CERTIFICATE GENERATION START === | survey_id=X | user_input_id=Y | ...

# Generation Success
INFO: === CERTIFICATE GENERATION SUCCESS === | survey_id=X | pdf_size_bytes=Z | duration_ms=W

# Generation Failure
ERROR: === CERTIFICATE GENERATION FAILURE === | survey_id=X | error_type=... | error_message=...
```

### LibreOffice Logs

```
# Conversion Start
INFO: >>> LibreOffice conversion START | docx_path=... | attempt=X

# Conversion Success
INFO: >>> LibreOffice conversion SUCCESS | pdf_size_bytes=Z | duration_ms=W

# Conversion Failure
ERROR: >>> LibreOffice conversion FAILURE | exit_code=X | stderr=...

# LibreOffice Unavailable
CRITICAL: !!! LIBREOFFICE UNAVAILABLE !!! | error_message=...
```

## Administrator Notifications

### LibreOffice Unavailable

**Trigger**: LibreOffice cannot be found or fails to execute

**Throttling**: Once per hour

**Recipients**: Users in `base.group_system` (Settings access)

**Content**:
- Error details
- Installation instructions (Ubuntu, CentOS, macOS)
- Action required
- Context information

### Repeated Generation Failures

**Trigger**: 3 consecutive certificate generation failures for a survey

**Throttling**: Once per hour per survey

**Recipients**: Users in `base.group_system` (Settings access)

**Content**:
- Survey information
- Failure count
- Recent error messages (last 5)
- Possible causes
- Recommended actions

## Monitoring Checklist

### Daily Checks
- [ ] Review ERROR and CRITICAL logs
- [ ] Check for LibreOffice unavailability alerts
- [ ] Monitor certificate generation success rate

### Weekly Checks
- [ ] Review WARNING logs for patterns
- [ ] Check average generation duration
- [ ] Verify notification throttling is working
- [ ] Review failure counts per survey

### Monthly Checks
- [ ] Analyze performance trends
- [ ] Review log file sizes and rotation
- [ ] Update notification thresholds if needed
- [ ] Check for recurring error patterns

## Troubleshooting Guide

### Issue: LibreOffice Unavailable

**Symptoms**:
- CRITICAL logs about LibreOffice
- Administrator notifications
- Certificate generation fails

**Resolution**:
1. Install LibreOffice:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install libreoffice
   
   # CentOS/RHEL
   sudo yum install libreoffice
   
   # macOS
   brew install --cask libreoffice
   ```
2. Restart Odoo service
3. Verify with: `libreoffice --version`

### Issue: Repeated Generation Failures

**Symptoms**:
- Multiple ERROR logs for same survey
- Administrator notification after 3 failures

**Resolution**:
1. Check Odoo logs for specific error messages
2. Verify template file is valid DOCX
3. Check placeholder mappings configuration
4. Verify server resources (disk space, memory)
5. Test certificate generation manually
6. Review LibreOffice subprocess logs

### Issue: High Generation Duration

**Symptoms**:
- `duration_ms` values consistently high in logs

**Resolution**:
1. Check server CPU and memory usage
2. Verify LibreOffice is not running multiple instances
3. Check template file size
4. Consider optimizing template (compress images)
5. Review concurrent generation load

## Configuration

### Notification Throttling

**File**: `services/admin_notifier.py`

```python
# Change throttle period (default: 60 minutes)
AdminNotifier.THROTTLE_MINUTES = 120  # 2 hours
```

### Failure Threshold

**File**: `services/admin_notifier.py`

```python
# Change failure threshold (default: 3)
AdminNotifier.FAILURE_THRESHOLD = 5  # Notify after 5 failures
```

### Log Level

**File**: `odoo.conf`

```ini
[options]
log_level = info  # debug, info, warning, error, critical
```

## Useful Log Queries

### Find All Certificate Generation Failures
```bash
grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log
```

### Find LibreOffice Errors
```bash
grep "LibreOffice" /var/log/odoo/odoo.log | grep -E "ERROR|CRITICAL"
```

### Count Successful Generations Today
```bash
grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | grep "$(date +%Y-%m-%d)" | wc -l
```

### Find Slow Generations (>5 seconds)
```bash
grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | grep -E "duration_ms=[5-9][0-9]{3}|duration_ms=[1-9][0-9]{4}"
```

### Check Notification History
```bash
grep "Sent.*notification to.*administrators" /var/log/odoo/odoo.log
```

## Performance Metrics

### Key Metrics to Track

| Metric | Good | Warning | Critical |
|--------|------|---------|----------|
| Generation Duration | <3s | 3-10s | >10s |
| Success Rate | >95% | 90-95% | <90% |
| PDF Size | <500KB | 500KB-2MB | >2MB |
| LibreOffice Conversion | <2s | 2-5s | >5s |

### Calculating Metrics

**Success Rate**:
```bash
# Count successes
SUCCESS=$(grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | wc -l)

# Count failures
FAILURES=$(grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log | wc -l)

# Calculate rate
echo "scale=2; $SUCCESS / ($SUCCESS + $FAILURES) * 100" | bc
```

**Average Duration**:
```bash
grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | \
  grep -oP "duration_ms=\K[0-9.]+" | \
  awk '{sum+=$1; count++} END {print sum/count}'
```

## Best Practices

### For Developers
1. Always use CertificateLogger for certificate operations
2. Include relevant context in log calls
3. Use appropriate log levels
4. Log both start and end of operations
5. Include duration metrics for performance tracking

### For Administrators
1. Monitor CRITICAL and ERROR logs daily
2. Set up log rotation to manage disk space
3. Configure external monitoring for CRITICAL logs
4. Review notification settings based on usage
5. Keep LibreOffice updated

### For Production
1. Set log level to INFO (not DEBUG)
2. Configure log rotation (daily or weekly)
3. Set up external log aggregation
4. Monitor disk space for log files
5. Test notification delivery regularly

## Support

### Getting Help

1. **Check Logs**: Review Odoo logs for detailed error messages
2. **Check Notifications**: Review administrator notifications for guidance
3. **Test Manually**: Try generating a certificate manually from survey form
4. **Verify LibreOffice**: Run `libreoffice --version` to verify installation
5. **Check Resources**: Verify server has adequate disk space and memory

### Reporting Issues

When reporting issues, include:
- Relevant log excerpts (with timestamps)
- Survey ID and title
- Error messages from notifications
- LibreOffice version (`libreoffice --version`)
- Odoo version
- Steps to reproduce

## Quick Commands

```bash
# View real-time logs
tail -f /var/log/odoo/odoo.log | grep -E "CERTIFICATE|LibreOffice"

# Check LibreOffice installation
libreoffice --version

# Test LibreOffice conversion
libreoffice --headless --convert-to pdf --outdir /tmp /path/to/test.docx

# Count today's certificate generations
grep "CERTIFICATE GENERATION" /var/log/odoo/odoo.log | grep "$(date +%Y-%m-%d)" | wc -l

# Find recent failures
grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log | tail -20

# Check notification throttling
grep "Notification throttled" /var/log/odoo/odoo.log | tail -10
```

---

**Last Updated**: 2024-01-15

**Module Version**: 19.0.1.0.0