What It Does
A forgotten debug.log can grow to gigabytes and take a site down when the disk fills. Debug Log Guard resolves the active log target (WP_DEBUG_LOG, a custom path, or php.ini's error_log), streams it without ever loading the whole file into memory, and groups repeated errors into a deduplicated summary so you can see the actual culprits. One-click actions — compact, rotate, or clear — always create a backup first, and an hourly size-guard cron watches the file and acts automatically when it crosses your threshold. The module reads and post-processes the log; it never changes how PHP writes errors.
Features
- Resolves the actual log target the way WordPress does: WP_DEBUG_LOG only counts when WP_DEBUG is on, custom log paths are honored, and php.ini's error_log is the fallback — instead of assuming wp-content/debug.log
- Grouped, deduplicated error summary: identical errors (differing only by timestamp) collapse into one row with count, source attribution (which plugin, theme, or core file), and first/last seen timestamps
- Optional aggressive grouping that masks volatile tokens (hex addresses, line numbers, numeric IDs) so near-identical errors also group together
- Live tail of the last 200 log lines, loaded on demand
- Streaming reads with a scan cap (default 100MB) — even multi-gigabyte logs never exhaust PHP memory
- Compact: collapses repeated lines in place, annotating each with its repeat count and time range — backup first, atomic temp-file + rename, and any lines appended during the run are preserved
- Compact refuses to run when free disk space is insufficient, when there are too many distinct lines, or when it would exceed a 20-second time budget — the original file is always left untouched on abort
- Rotate: rename-only operation (safe for giant files) that archives the log and starts a fresh empty one
- Clear: empties the log after saving a backup
- Download the full log as a file, streamed in chunks
- Hourly size-guard cron: stats the file (an O(1) check), and when it crosses your threshold runs your chosen action automatically; files past the hard ceiling (default 1GB) are force-rotated instead of compacted
- Configurable backup retention (how many .bak / rotated files to keep)
- Warns when debug logging is on in production — including whether the log sits inside wp-content where it may be reachable over HTTP — and links to Config Manager to turn it off
- Detects unmanageable targets (syslog, /dev/stderr) and disables file actions instead of failing confusingly
How to Use
-
Open Debug Log Guard
Go to WP Multitool > Debug Log Guard. The status card shows the resolved log path, its current size, and whether WP_DEBUG is on. If debug logging is enabled in production, a warning explains why that matters.
-
Review the repeated errors
The summary table groups identical errors with counts and source attribution. A single deprecation notice firing 400,000 times from one plugin is the usual reason a log balloons.
-
Fix the source, then act on the file
Click "Compact now" to collapse the repeats in place (a backup is saved first), or "Rotate" for very large files. "Clear" empties the log after backing it up. You can download the log before acting.
-
Configure the size guard
Set your threshold (default 50MB) and the automatic action (compact, rotate, or clear). The hourly cron then watches the file for you — it only ever stats the file until the threshold is crossed.
-
Turn debug logging off in production
The size guard is damage control. If you are not actively debugging, follow the link to Config Manager and turn WP_DEBUG_LOG off.
Settings
| Setting | Default | Description |
|---|---|---|
| Enable hourly size guard | On |
Hourly WP-Cron check of the log size. Only ever stats the file until the threshold is exceeded. |
| Threshold (MB) | 50 |
When the log exceeds this size, the size guard runs the configured action automatically. |
| Guard action | Compact |
What the size guard does when triggered: compact, rotate, or clear. Files over the hard ceiling (1GB) are always rotated instead of compacted. |
| Keep backups | 1 |
How many backup/rotated copies of the log to retain. |
| Aggressive grouping | Off |
Masks numeric IDs, line numbers, and hex addresses when grouping, so near-identical errors collapse into one row. |
FAQ
Does this change how PHP or WordPress writes errors?
No. Debug Log Guard is strictly read-and-post-process: it never hooks into PHP's error write path, installs no drop-in, and does not filter what gets logged. It manages the file after the fact.
Can compacting lose log entries?
The information is preserved in condensed form: each repeated line becomes a single line annotated with its repeat count and first/last timestamps. A full backup is saved before any write, the rewrite is atomic (temp file + rename), and lines appended while the compaction runs are carried over verbatim. If anything cannot be done safely — low disk, too large, too many distinct lines — the operation aborts with the original untouched.
My log is already several gigabytes. What should I do?
Use Rotate, not Compact. Rotation is a rename-only operation that needs no extra disk or memory and completes instantly, archiving the giant file and starting a fresh log. The automatic size guard never compacts a file past the hard ceiling (default 1GB) — it rotates instead.
Why does it say the log target "cannot be managed"?
Your error log goes to syslog or a stream like /dev/stderr (common in containers) rather than a regular file. There is no file to compact or rotate, so the file actions are disabled. The summary and tail also require a regular file.
Why the warning about debug logging in production?
Two reasons. Every logged notice costs disk writes on every request, and the default wp-content/debug.log location may be reachable over HTTP, leaking file paths and internals to anyone who guesses the URL. Unless you are actively debugging, WP_DEBUG_LOG should be off in production — Config Manager can toggle it.
Ready to optimize your WordPress site?
Join developers using WP Multitool to debug, optimize, and maintain WordPress.
Get WP Multitool