Skip to content

Adam Greenwell

Debug System

Guard Dog includes a comprehensive debug logging system to help troubleshoot issues and monitor plugin behavior.

Overview

The debug system provides:

  • ✅ Multiple log levels (ERROR, WARNING, INFO, DEBUG)
  • ✅ Component-specific logging
  • ✅ Structured log output
  • ✅ Writes to WordPress debug.log
  • ✅ Privacy-safe logging (no passwords)
  • ✅ Integration with WordPress debug system

Enabling Debug Logging

Prerequisites

Guard Dog writes to the WordPress debug log. Ensure WordPress debugging is enabled:

In wp-config.php, add or verify:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false); // Don't display errors on screen

This creates the /wp-content/debug.log file that Guard Dog will write to.

Step 1: Access Debug Settings

Navigate to Guard Dog → Settings → Debug Settings

Step 2: Enable Logging

  1. Check “Enable Debug Logging”
  2. Choose your Debug Level
  3. Click Save Changes

Guard Dog will now write debug entries to /wp-content/debug.log alongside WordPress core and other plugin logs.

Debug Levels

ERROR (Recommended for Production)

What it logs: Only critical errors that prevent features from working

Examples:

  • Database connection failures
  • CAPTCHA verification errors
  • Failed external API calls
  • Missing required settings

Use when: Running in production, want minimal logging

Log volume: Very low

WARNING (Recommended for Monitoring)

What it logs: Errors + potential issues that don’t break functionality

Examples:

  • Deprecated function usage
  • Configuration issues
  • Missing optional settings
  • Unusual behavior

Use when: Monitoring production site for issues

Log volume: Low

INFO (Recommended for Troubleshooting)

What it logs: Errors + Warnings + general operational information

Examples:

  • Login attempts
  • Lockout events
  • 2FA verification
  • Access control decisions
  • Feature activation

Use when: Investigating specific issue, understanding flow

Log volume: Medium

DEBUG (Recommended for Development Only)

What it logs: Everything – complete detailed execution flow

Examples:

  • Function entry/exit
  • Variable values
  • Query parameters
  • API request/response details
  • Internal state changes

Use when: Deep troubleshooting, development, finding bugs

Log volume: Very high

Reading Debug Logs

Log Format

Guard Dog entries in the debug.log follow this format:

[Timestamp] Guard Dog - LEVEL [Component] Message
Context data (if any)

Example:

[2024-10-23 14:30:15] Guard Dog - ERROR [CAPTCHA] reCAPTCHA verification failed
IP: 203.0.113.50
Response: invalid-input-secret

The “Guard Dog” prefix helps identify Guard Dog entries in the shared debug.log file.

Log Components

Timestamp: When event occurred (WordPress timezone)

Level: ERROR, WARNING, INFO, or DEBUG

Component: Which Guard Dog feature:

  • [Login URL] – Custom login URL
  • [CAPTCHA] – CAPTCHA verification
  • [2FA] – Two-factor authentication
  • [Login Limiting] – Login attempt limiting
  • [Access Control] – IP/username blocking
  • [Activity Log] – Activity logging
  • [Temp Access] – Temporary user access
  • [Email Provider] – Email sending
  • [Core] – Core plugin functionality

Message: Human-readable description

Context: Additional relevant data (IP addresses, usernames, details)

Viewing Logs

In WordPress Admin

  1. Go to Guard Dog → Settings → Debug Settings
  2. Scroll to Debug Log Viewer
  3. Guard Dog entries are displayed (filtered from the full debug.log)
  4. Logs are displayed in reverse chronological order (newest first)

Note: The WordPress debug.log file contains entries from WordPress core, Guard Dog, and other plugins. The Debug Log Viewer automatically filters to show only Guard Dog entries.

Filtering Logs

By Level:

  • Select level from dropdown
  • Shows only that level and above

By Component:

  • Select component from dropdown
  • Shows only logs from that feature

By Date:

  • Enter date range
  • Shows logs from that period

By Search:

  • Enter search term
  • Searches in message and context

Accessing Logs

Via WordPress Admin:

  1. Go to Guard Dog → Settings → Debug Settings
  2. View logs in the Debug Log Viewer

Via FTP/File Manager:

  1. Access your site files
  2. Navigate to /wp-content/debug.log
  3. Download the file for offline analysis

Use for:

  • Sharing with support
  • Offline analysis
  • Archival before clearing

Common Scenarios

Scenario 1: Troubleshooting Login Issues

Enable:

  • Debug Level: INFO
  • Component: All

Reproduce:

  1. Try to log in
  2. Check debug log
  3. Look for entries with [Login Limiting], [Access Control], [CAPTCHA], [2FA]

What to look for:

[2024-10-23 14:30:15] Guard Dog - INFO [Access Control] Checking IP: 203.0.113.50
[2024-10-23 14:30:15] Guard Dog - INFO [Access Control] IP is blacklisted, blocking login

Scenario 2: CAPTCHA Not Working

Enable:

  • Debug Level: DEBUG
  • Component: CAPTCHA

Reproduce:

  1. Access login page
  2. Complete CAPTCHA
  3. Submit form
  4. Check debug log

What to look for:

[2024-10-23 14:30:15] Guard Dog - DEBUG [CAPTCHA] Sending verification request to reCAPTCHA
Request data: {...}
[2024-10-23 14:30:16] Guard Dog - ERROR [CAPTCHA] Verification failed
Response: invalid-input-secret

Scenario 3: 2FA Codes Not Working

Enable:

  • Debug Level: DEBUG
  • Component: 2FA

Reproduce:

  1. Log in with username/password
  2. Enter 2FA code
  3. Check debug log

What to look for:

[2024-10-23 14:30:15] Guard Dog - DEBUG [2FA] Verifying TOTP code for user: john
[2024-10-23 14:30:15] Guard Dog - DEBUG [2FA] Expected code: 123456, Provided code: 654321
[2024-10-23 14:30:15] Guard Dog - WARNING [2FA] Code mismatch, verification failed

Scenario 4: Email Not Sending

Enable:

  • Debug Level: DEBUG
  • Component: Email Provider

Reproduce:

  1. Trigger email 2FA
  2. Check debug log

What to look for:

[2024-10-23 14:30:15] Guard Dog - DEBUG [Email Provider] Sending email via Resend
To: [email protected]
[2024-10-23 14:30:16] Guard Dog - ERROR [Email Provider] API request failed
Status code: 403
Response: Forbidden - Invalid API key

Scenario 5: Lockouts Not Working

Enable:

  • Debug Level: INFO
  • Component: Login Limiting

Reproduce:

  1. Make failed login attempts
  2. Check debug log after each attempt

What to look for:

[2024-10-23 14:30:15] Guard Dog - INFO [Login Limiting] Failed login recorded
IP: 203.0.113.50, Attempts: 1/5
[2024-10-23 14:30:20] Guard Dog - INFO [Login Limiting] Failed login recorded
IP: 203.0.113.50, Attempts: 2/5
...
[2024-10-23 14:31:00] Guard Dog - INFO [Login Limiting] Lockout initiated
IP: 203.0.113.50, Expiry: 2024-10-23 14:46:00

Privacy & Security

What IS Logged

✅ IP addresses
✅ Usernames (attempted logins)
✅ Timestamps
✅ Feature decisions (allow/block)
✅ Error messages
✅ Configuration values
✅ API responses (sanitized)

What is NOT Logged

❌ Passwords (never logged)
❌ 2FA codes (not stored)
❌ Recovery codes (not stored)
❌ API secret keys (redacted)
❌ Sensitive post/page content
❌ Payment information

Security Considerations

Log file location:

  • Stored in /wp-content/debug.log
  • Standard WordPress debug log location
  • Should be protected by .htaccess or server configuration
  • Not publicly accessible by default

Sensitive data:

  • API keys are redacted: sk-xxx...xxx (first/last 3 chars only)
  • Tokens are truncated: abc123...xyz789
  • Email addresses may be logged (for debugging email issues)

Access control:

  • Only administrators can view logs in WordPress admin
  • Debug log file accessible via FTP/server access
  • Clear logs to remove sensitive data

Log Management

Log File Size

Logs can grow large with DEBUG level:

Typical sizes:

  • ERROR level: 1-5 MB/month
  • WARNING level: 5-20 MB/month
  • INFO level: 20-100 MB/month
  • DEBUG level: 100-500 MB/month (high traffic)

Guard Dog writes to the standard WordPress debug log:

Log File Management

  • Location: /wp-content/debug.log
  • Shared: Same file used by WordPress core and other plugins
  • Growth: Can grow large over time
  • Management: Clear periodically to manage size

Clearing Logs

  1. Go to Debug Settings
  2. Click “Clear Debug Log”
  3. Confirm deletion
  4. All debug logs are deleted

When to clear:

  • After downloading for analysis
  • Logs growing too large
  • Finished troubleshooting
  • Before sharing site backup

Disabling Logging

  1. Go to Debug Settings
  2. Uncheck “Enable Debug Logging”
  3. Click Save Changes

Important: Disable DEBUG level on production sites after troubleshooting to avoid performance impact and excessive disk usage.

Sharing Logs for Support

When requesting support:

  1. Enable appropriate log level:
  • Start with INFO
  • Increase to DEBUG if requested
  1. Reproduce the issue:
  • Clear existing logs
  • Perform the action that causes the issue
  • Issue should now be logged
  1. Access the log:
  • Via FTP/File Manager: Download /wp-content/debug.log
  • Via WordPress admin: Copy relevant entries from Debug Log Viewer
  1. Filter Guard Dog entries:
  • Search for “Guard Dog” in the log file
  • Extract only Guard Dog-related lines
  • The log may contain entries from other plugins/WordPress
  1. Sanitize if needed:
  • Remove any sensitive data you don’t want to share
  • Search for your domain and replace with “example.com”
  • Search for sensitive IPs and replace
  1. Share with support:
  • Attach Guard Dog entries to support forum post
  • Or paste relevant excerpts only
  • Include: WordPress version, PHP version, Guard Dog version

Advanced Usage

Log File Location

Direct file access (via FTP/SSH):

/wp-content/debug.log

Guard Dog writes to the standard WordPress debug log file, which may also contain entries from WordPress core and other plugins.

Tailing Logs (Linux/Mac)

Monitor logs in real-time:

tail -f /path/to/wp-content/debug.log

Searching Logs (Command Line)

Find specific Guard Dog events:

# Find all Guard Dog CAPTCHA errors
grep "Guard Dog.*ERROR.*CAPTCHA" /wp-content/debug.log

# Find all Guard Dog events for specific IP
grep "Guard Dog" /wp-content/debug.log | grep "203.0.113.50"

# Count Guard Dog login failures
grep "Guard Dog.*Login Limiting.*Failed login" /wp-content/debug.log | wc -l

# View only Guard Dog entries
grep "Guard Dog" /wp-content/debug.log

Integrating with External Tools

Splunk, ELK, Graylog:

  • Parse Guard Dog log format
  • Import into log aggregation platform
  • Set up alerts and dashboards

Log rotation tools:

  • logrotate (Linux)
  • Compress old logs
  • Archive to cloud storage

Performance Impact

By Log Level

LevelPerformance Impact
ERRORNegligible (<1%)
WARNINGMinimal (1-2%)
INFOLow (2-5%)
DEBUGModerate (5-15%)

Recommendation: Use ERROR or WARNING in production, INFO/DEBUG only when troubleshooting.

Disk Space Impact

Typical daily log sizes (medium-traffic site):

  • ERROR: 0.1-0.5 MB
  • WARNING: 0.5-2 MB
  • INFO: 2-10 MB
  • DEBUG: 10-50 MB

High-traffic sites (100k+ visitors/day):

  • DEBUG level could generate 100+ MB/day
  • Monitor disk space
  • Use automatic rotation

Troubleshooting Debug System

Logs Not Appearing

Issue: Enabled logging but no logs appear

Causes:

  1. File permissions (can’t write)
  2. Disk space full
  3. PHP errors preventing logging

Solutions:

  1. Check /wp-content/ directory is writable (755 permissions)
  2. Verify WordPress debug logging is enabled (WP_DEBUG_LOG in wp-config.php)
  3. Check PHP error logs for Guard Dog errors
  4. Verify Guard Dog debug logging is enabled in settings
  5. Check /wp-content/debug.log file exists and is writable

Can’t Access Logs

Issue: Can’t view or access debug logs

Causes:

  1. File too large to view in browser
  2. Server timeout loading large file
  3. File permissions preventing access

Solutions:

  1. Access via FTP to download /wp-content/debug.log
  2. Use command line to view file (SSH access)
  3. Clear logs to reduce size
  4. View file in chunks using text editor
  5. Check file permissions (should be 644 or 664)

Logs Missing Events

Issue: Expected events not in log

Causes:

  1. Wrong log level (too high)
  2. Event occurred before logging enabled
  3. Event doesn’t trigger logging

Solutions:

  1. Lower log level to INFO or DEBUG
  2. Clear logs and reproduce
  3. Verify feature is actually running

Best Practices

  1. ✅ Use ERROR level in production unless troubleshooting
  2. ✅ Enable INFO/DEBUG only when needed then disable
  3. ✅ Download logs before clearing for records
  4. ✅ Monitor disk space with DEBUG level
  5. ✅ Sanitize logs before sharing remove sensitive data
  6. ✅ Use appropriate level for issue don’t always use DEBUG
  7. ✅ Review logs regularly catch issues early
  8. ✅ Clear logs after troubleshooting reduce disk usage
  9. ✅ Document findings note what you discovered
  10. ✅ Disable when done avoid performance impact