survey_custom_certificate_template/docs/LOGGING_MONITORING_QUICK_REFERENCE.md

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:

   # 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

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

Failure Threshold

File: services/admin_notifier.py

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

Log Level

File: odoo.conf

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

Useful Log Queries

Find All Certificate Generation Failures

grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log

Find LibreOffice Errors

grep "LibreOffice" /var/log/odoo/odoo.log | grep -E "ERROR|CRITICAL"

Count Successful Generations Today

grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | grep "$(date +%Y-%m-%d)" | wc -l

Find Slow Generations (>5 seconds)

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

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:

# 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:

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

# 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