whatsapp-logs

WhatsApp Bot Log Analysis

Log Files

Get today's logs:

ls -la logs/whatsapp-*.log 2>/dev/null | tail -5

JSON Log Structure

{
  "timestamp": "2026-01-04 14:30:45.123",
  "level": "INFO",
  "message": "Received message",
  "service": "whatsapp",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "handleMessage",
  "durationMs": 1234,
  "meta": {
    "from": "972501234567",
    "isGroup": false,
    "textPreview": "What's in progress?"
  }
}

Key Fields:

• service - Always "whatsapp" for bot logs
• correlationId - UUID linking logs for a single request
• operation - What operation was performed
• durationMs - Time taken in milliseconds
• meta.from - Sender phone number
• meta.isGroup - Whether message came from a group

Quick Commands

View Recent Activity

tail -50 logs/whatsapp-debug-$(date +%Y-%m-%d).log | jq .

Check Errors Today

cat logs/whatsapp-error-$(date +%Y-%m-%d).log 2>/dev/null | jq .

Watch Logs Real-Time

tail -f logs/whatsapp-debug-$(date +%Y-%m-%d).log | jq .

Find Messages From a Phone Number

grep '"from":"972501234567"' logs/whatsapp-debug-*.log | jq .

Check Connection Status

grep -E "(Connected|Disconnected|reconnect)" logs/whatsapp-debug-*.log | tail -10 | jq .

Common Debugging Scenarios

Bot Not Responding

# Check if messages are being received
grep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -5 | jq '{time: .timestamp, from: .meta.from, text: .meta.textPreview}'

# Check for processing errors
grep -E '"level":"ERROR"' logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -10 | jq .

Connection Issues

# Check connection events
grep -E "(connection|reconnect|disconnect)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message}'

# Check QR code events
grep "QR" logs/whatsapp-debug-*.log | tail -5 | jq .

Voice Message Issues

# Check transcription activity
grep -E "(transcri|voice|audio)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message, duration: .meta.duration}'

Group Message Issues

# Check group activity
grep '"isGroup":true' logs/whatsapp-debug-*.log | tail -10 | jq '{time: .timestamp, group: .meta.groupId, from: .meta.from}'

# Check group metadata fetching
grep "group.*metadata" logs/whatsapp-debug-*.log | jq .

Image Processing Issues

# Check image downloads
grep -E "(image|media)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message, size: .meta.size}'

Agent/Claude Issues

# Check agent processing
grep '"service":"whatsapp"' logs/whatsapp-debug-*.log | grep -E "(process|agent)" | jq .

Trace a Single Request

1. Find the correlation ID from an error or message:

grep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -1 | jq .correlationId

2. Trace all related logs:

grep "CORRELATION_ID_HERE" logs/whatsapp-debug-*.log | jq .

Performance Analysis

Find Slow Operations (>5s)

grep durationMs logs/whatsapp-debug-*.log | jq 'select(.durationMs > 5000) | {msg: .message, duration: .durationMs}'

Message Processing Times

grep "Sent response" logs/whatsapp-debug-*.log | jq '{time: .timestamp, duration: .meta.responseTime}'

Count Messages Today

grep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | wc -l

Error Rate

echo "Errors: $(cat logs/whatsapp-error-$(date +%Y-%m-%d).log 2>/dev/null | wc -l)"
echo "Total: $(cat logs/whatsapp-debug-$(date +%Y-%m-%d).log | wc -l)"

Log Rotation Configuration

Log files are named: whatsapp-debug-YYYY-MM-DD.log Old logs are compressed: whatsapp-debug-YYYY-MM-DD.log.gz

Reading Compressed Logs

# Read compressed log
zcat logs/whatsapp-debug-2026-01-01.log.gz | jq . | head -50

# Search in compressed logs
zgrep "error" logs/whatsapp-debug-*.log.gz | head -20

Log Level Configuration

Set via LOG_LEVEL environment variable when starting the bot:

• error - Only errors
• warn - Errors and warnings
• info - Normal operation (default)
• debug - Verbose debugging

LOG_LEVEL=debug npm run whatsapp

Debugging Tips

1. Start with errors - Check whatsapp-error-*.log first
2. Use correlation IDs - Links all logs for a single message flow
3. Check timestamps - Gaps indicate hanging operations
4. Look at meta field - Contains phone numbers, group IDs, message previews
5. Use jq for filtering - JSON format enables powerful queries
6. Compare durations - Sudden increases indicate API issues
7. Check both log files - Debug logs show full flow, error logs show failures