📝 Log Troubleshooting

🚨 Symptom: Logs no aparecen o faltan entradas

Quick Checks

# 1. Check log file exists
ls -la logs/
# Expected: audiolab.log, error.log, debug.log

# 2. Check file permissions
ls -l logs/audiolab.log
# Expected: -rw-r--r-- (644) or -rw-rw-r-- (664)

# 3. Check disk space
df -h
# Expected: > 1GB available

# 4. Check log config loaded
grep "log" config/logging.conf
# Expected: log level, file paths, rotation settings

# 5. Check process has write access
touch logs/test.log && rm logs/test.log
# Expected: No permission denied error

🔧 Common Issues & Solutions

Issue 1: No Log File Created

Symptoms: - logs/ directory exists but empty - No error messages visible - Application runs but silent

Causes & Fixes:

╔════════════════════════════════════════════════════════════╗
║ Cause               │ Diagnostic           │ Fix          ║
╠═════════════════════╪══════════════════════╪══════════════╣
║ Permission denied   │ ls -l logs/          │ chmod 755    ║
║ Path doesn't exist  │ ls logs/             │ mkdir logs/  ║
║ Logger not init     │ Check init() called  │ Call init()  ║
║ Wrong config path   │ Check CONFIG_PATH    │ Fix path     ║
║ SELinux blocking    │ getenforce           │ setenforce 0 ║
╚════════════════════════════════════════════════════════════╝

Quick Fix:

# Create logs directory with correct permissions
mkdir -p logs/
chmod 755 logs/

# Verify write access
echo "test" > logs/test.log
cat logs/test.log
rm logs/test.log

Issue 2: Logs Stop Mid-Line (Buffer Overflow)

Symptoms:

[INFO] Processing audio buf
[INFO] Filter applying re
[INFO] Output written to

Cause: Log buffer not flushed before crash/exit

Fix:

// Flush after critical operations
logger.info("Starting critical operation");
logger.flush();  // Force write to disk

// Auto-flush on errors
logger.error("Critical error occurred");
// Automatically flushes

// Flush on shutdown
void shutdown() {
    logger.info("Shutting down...");
    logger.flush();
    logger.close();
}

Issue 3: Permission Denied

Symptoms:

ERROR: Failed to open log file: Permission denied
ERROR: Could not write to /var/log/audiolab.log

Diagnostic:

# Check file ownership
ls -l /var/log/audiolab.log
# Shows: -rw-r--r-- 1 root root

# Check current user
whoami
# Shows: audiolab (not root)

Fix:

# Option 1: Change ownership
sudo chown audiolab:audiolab /var/log/audiolab.log

# Option 2: Add to group
sudo usermod -a -G adm audiolab

# Option 3: Use user directory
# In config:
log.file = ${HOME}/logs/audiolab.log

Issue 4: Disk Full

Symptoms:

ERROR: No space left on device
WARN: Log file write failed

Diagnostic:

# Check disk usage
df -h
# Shows: /var/log 100% used

# Check log file sizes
du -sh logs/*
# Shows: audiolab.log 25G

Immediate Fix:

# Compress old logs
gzip logs/audiolab-*.log

# Remove oldest
find logs/ -name "*.log.gz" -mtime +30 -delete

# Truncate current (CAREFUL!)
> logs/audiolab.log  # Empties file

Permanent Fix:

# Enable log rotation
rotation:
  max_size: 100MB      # Rotate at 100MB
  max_files: 10        # Keep 10 files
  compress: true       # Compress rotated files

Issue 5: Log Rotation Stuck

Symptoms: - Log file grows beyond max_size - No .1, .2 files created - Rotation timestamp not updating

Diagnostic:

# Check rotation config
cat config/logging.conf | grep rotation

# Check last rotation
ls -lht logs/audiolab.log*
# Should show multiple files with recent timestamps

Fix:

# Manual rotation
logrotate -f /etc/logrotate.d/audiolab

# Or restart application
sudo systemctl restart audiolab
# Triggers rotation on start

Issue 6: Logs in Wrong Location

Symptoms: - Can't find log files - Application says "logging enabled" but no output

Find logs:

# Search for log files
find / -name "audiolab.log" 2>/dev/null

# Check config file
grep "log" config/*.conf

# Check environment variables
env | grep LOG

# Check running process
lsof -p $(pidof audiolab) | grep log

Issue 7: Log Level Too High

Symptoms: - Important messages missing - Only ERROR logs visible - DEBUG logs not appearing

Check current level:

# In config
grep "log.level" config/logging.conf
# Shows: log.level = ERROR

# In code
logger.getLevel()
# Returns: LogLevel::ERROR

Fix:

// Temporarily lower level
logger.setLevel(LogLevel::DEBUG);

// Or in config
// log.level = DEBUG

Issue 8: Character Encoding Issues

Symptoms:

[INFO] Processing file: caf�.wav
[ERROR] Invalid UTF-8 sequence: �

Fix:

// Sanitize before logging
std::string sanitize(const std::string& str) {
    std::string result;
    for (char c : str) {
        if (isprint(c) || c == '\n' || c == '\t') {
            result += c;
        } else {
            result += "?";
        }
    }
    return result;
}

logger.info("Processing: " + sanitize(filename));

🐛 Advanced Debugging

Enable Trace Logging

// Maximum verbosity
logger.setLevel(LogLevel::TRACE);

// Log function entry/exit
#define TRACE_FUNC() \
    logger.trace("ENTER: " + std::string(__FUNCTION__))

void processAudio() {
    TRACE_FUNC();
    // ... processing ...
    logger.trace("EXIT: " + std::string(__FUNCTION__));
}

Check Logger Initialization

// Verify logger is working
void testLogger() {
    logger.trace("TRACE message");
    logger.debug("DEBUG message");
    logger.info("INFO message");
    logger.warn("WARN message");
    logger.error("ERROR message");
    logger.fatal("FATAL message");

    // Check if all appear in log file
}

Monitor Logs in Real-Time

# Tail all log files
tail -f logs/*.log

# Filter for errors
tail -f logs/audiolab.log | grep ERROR

# Highlight errors
tail -f logs/audiolab.log | grep --color=always -E "ERROR|WARN|$"

# On Windows (PowerShell)
Get-Content logs\audiolab.log -Wait -Tail 50

📊 Log Health Check Script

#!/bin/bash

echo "=== Log Health Check ==="

# 1. Check files exist
echo -n "Log files exist: "
if [ -f logs/audiolab.log ]; then
    echo "✓"
else
    echo "✗ (missing)"
fi

# 2. Check permissions
echo -n "Write permissions: "
if [ -w logs/audiolab.log ]; then
    echo "✓"
else
    echo "✗ (denied)"
fi

# 3. Check disk space
echo -n "Disk space: "
SPACE=$(df -h logs/ | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $SPACE -lt 90 ]; then
    echo "✓ ($SPACE%)"
else
    echo "⚠ ($SPACE% - low space!)"
fi

# 4. Check log rotation
echo -n "Rotation working: "
COUNT=$(ls -1 logs/audiolab.log* 2>/dev/null | wc -l)
if [ $COUNT -gt 1 ]; then
    echo "✓ ($COUNT files)"
else
    echo "⚠ (not rotating)"
fi

# 5. Check recent activity
echo -n "Recent logs: "
RECENT=$(find logs/audiolab.log -mmin -5)
if [ -n "$RECENT" ]; then
    echo "✓ (active)"
else
    echo "⚠ (no recent writes)"
fi

# 6. Check log size
echo -n "Log size: "
SIZE=$(du -h logs/audiolab.log | cut -f1)
echo "$SIZE"

# 7. Check for errors
echo -n "Recent errors: "
ERRORS=$(tail -1000 logs/audiolab.log | grep -c ERROR)
echo "$ERRORS in last 1000 lines"

🛠️ Diagnostic Tools

Log Analyzer

#!/usr/bin/env python3
import re
from collections import Counter

def analyze_log(filename):
    levels = Counter()
    errors = []

    with open(filename) as f:
        for line in f:
            # Count log levels
            match = re.search(r'\[(TRACE|DEBUG|INFO|WARN|ERROR|FATAL)\]', line)
            if match:
                levels[match.group(1)] += 1

            # Collect errors
            if 'ERROR' in line or 'FATAL' in line:
                errors.append(line.strip())

    print("Log Level Distribution:")
    for level, count in levels.most_common():
        print(f"  {level}: {count}")

    print(f"\nTotal Errors: {len(errors)}")
    if errors:
        print("\nRecent Errors:")
        for error in errors[-5:]:
            print(f"  {error}")

if __name__ == "__main__":
    analyze_log("logs/audiolab.log")

Real-Time Error Monitor

#!/bin/bash

# Monitor logs and alert on errors
tail -f logs/audiolab.log | while read line; do
    if echo "$line" | grep -q "ERROR\|FATAL"; then
        # Send alert
        echo "🚨 ERROR DETECTED: $line"

        # Could also:
        # - Send email
        # - Post to Slack
        # - Trigger pager
    fi
done

📋 Troubleshooting Checklist

□ Log directory exists and is writable
□ Log files have correct permissions (644 or 664)
□ Sufficient disk space (> 1GB)
□ Logger initialized before use
□ Config file loaded successfully
□ Log level set appropriately
□ Rotation configured and working
□ No SELinux/AppArmor blocking
□ Process has necessary privileges
□ Logs flushed before exit

🚨 Emergency Recovery

Lost All Logs

# 1. Enable syslog fallback
logger -t audiolab "Logging to syslog"

# 2. Check system logs
journalctl -u audiolab -n 100

# 3. Enable console output
export AUDIOLAB_LOG_STDOUT=1

# 4. Increase verbosity
export AUDIOLAB_LOG_LEVEL=DEBUG

Corrupted Log File

# 1. Backup corrupted file
cp logs/audiolab.log logs/audiolab.log.corrupted

# 2. Extract valid lines
grep -a "^\[" logs/audiolab.log.corrupted > logs/audiolab.log

# 3. Or start fresh
mv logs/audiolab.log logs/audiolab.log.bad
touch logs/audiolab.log
chmod 644 logs/audiolab.log

Logs Too Large to Open

# Split into chunks
split -l 100000 logs/audiolab.log logs/chunk_

# View recent entries
tail -n 1000 logs/audiolab.log | less

# Search without opening
grep "ERROR" logs/audiolab.log | tail -n 50

# Compress old data
gzip logs/audiolab.log
zgrep "pattern" logs/audiolab.log.gz

📞 Getting Help

Information to Collect

# System info
uname -a
df -h
free -m

# Log files
ls -lah logs/

# Config
cat config/logging.conf

# Recent errors
tail -100 logs/audiolab.log | grep ERROR

# Process info
ps aux | grep audiolab
lsof -p $(pidof audiolab) | grep log

Support Checklist

When reporting log issues, provide: - Operating system and version - Application version - Log config file - Directory permissions (ls -lah logs/) - Disk space (df -h) - Recent log entries (last 50 lines) - Error messages (if any) - Steps to reproduce

🔗 Related Docs

• Log Configuration Guide
• Log Levels Reference
• Rotation Setup