WP Debug Toolkit (WPDT) automatically deletes query log files based on two independent triggers: file age and total storage size. The two triggers run on different schedules and operate independently. Navigate to WP Debug Toolkit › Settings › Log Cleanup and expand the Query Logs card to configure both thresholds.
Query log retention is the system that WPDT uses to prevent query log files from accumulating unchecked on disk. Sites running always-on logging or frequent recording sessions write encrypted log files to wp-content/uploads/debug-toolkit/queries/ continuously, organized by month. Without retention limits, those files grow until they consume your available storage.
Unlike error log cleanup, query log cleanup has no archiving step and no cleanup method selector. When either retention trigger fires, WPDT immediately deletes the log files. There is no intermediate archive state.
WPDT manages query log files through two independent triggers that operate on different schedules. The size trigger runs on a fixed daily cycle. The age trigger runs in the background during normal logging activity and always fires when you run a manual cleanup. Both evaluate the same directory, but they fire separately, and neither depends on the other.
WPDT checks for old query log files periodically in the background as part of its normal logging activity, rather than on a fixed daily schedule. It determines each file’s age by when it was last written to. A file that is still receiving new log entries will be treated as recent, even if the month it covers has passed.
When a file’s last-write time falls outside your configured threshold, WPDT deletes it. Age-based cleanup also runs whenever you trigger a manual cleanup from the admin UI or via WP-CLI. Setting Delete logs older than (days) to 0 disables this trigger entirely. The valid range is 0–365 days.
WPDT calculates the total storage consumed by all files in wp-content/uploads/debug-toolkit/queries/. When the total exceeds the configured MB threshold, WPDT deletes the oldest log files first until the total falls to 90% of the threshold, providing a small buffer before the next write triggers another check.
This trigger fires independently of the age-based trigger. A large volume of recent logs can trigger size-based cleanup even when none of the files are old enough to hit the age threshold.
The valid range for this setting is 1–5000 MB. Unlike the age threshold, it cannot be set to 0. At the default of 100 MB, WPDT removes the oldest files when the combined query log storage exceeds that limit.
The higher default for query logs (100 MB versus 50 MB for the error log) reflects the difference in data density: each query log entry stores an encrypted JSON fragment containing the SQL statement, execution time, full backtrace, and component attribution. A single recording session on a complex page load generates significantly more data than a comparable set of error log entries.
✅ Key Guarantees
dbtk_daily_log_cleanup WordPress cron action, the same action that manages error log cleanup. Age-based cleanup runs separately, on an opportunistic basis during query log writes and during manual cleanup.| Term | What It Means |
|---|---|
| Delete logs older than (days) | The age threshold for query log retention. WPDT deletes log files older than this number of days. Cleanup runs in the background during logging activity and on manual cleanup, not on the daily cron cycle. Default: 30 days. Set to 0 to disable age-based cleanup. |
| Delete oldest when total exceeds (MB) | The total storage limit for all query log files combined. When the total exceeds this limit, WPDT deletes the oldest files first until storage falls to 90% of the threshold. Default: 100 MB. Valid range: 1–5000 MB. |
queries-YYYY-MM.log | The naming format for monthly query log files stored in wp-content/uploads/debug-toolkit/queries/. WPDT determines each file’s age from when it was last written to, not from the date in the filename. |
| Daily cleanup cycle | The WordPress cron-based task (dbtk_daily_log_cleanup) that WPDT runs automatically each day. For query logs, this cycle applies only the size-based cleanup rule. Age-based cleanup runs separately in the background during logging activity, not on this schedule. |
Go to WP Debug Toolkit › Settings › Log Cleanup and expand the Query Logs card.
Enter the number of days in Delete logs older than (days). Lower this value on sites with heavy query logging or always-on logging to prevent file accumulation.
Enter the storage limit in Delete oldest when total exceeds (MB). Lower this value if disk space is constrained.
Click Save Settings. The updated size threshold applies on the next daily cleanup cycle. The updated age threshold takes effect the next time background cleanup runs during logging activity.
Note: To clear query logs immediately, without waiting for the scheduled cycle, click Clear Logs in the Clear Query Logs row on the Database Queries card under WP Debug Toolkit › Overview. To clear all query log files from the command line, run wp dbtk query-log clear --all.
Likely cause: Always-on logging is generating new log files faster than cleanup can remove them, or the size threshold is set too high relative to the logging volume.
Fix: Lower the Delete oldest when total exceeds (MB) value in the Query Logs card to a limit that matches your available disk space. You should also consider switching from always-on logging to time-limited recording sessions, which generate smaller, more targeted log files.
Likely cause: No recording session has been completed yet, or always-on logging was not active long enough to generate a log file. Query log files are only written when queries have been captured.
Fix: Start a recording session and load a page on the front end or in wp-admin, then check wp-content/uploads/debug-toolkit/queries/ for a file matching the current month.
No. Shareable recording files use a different naming format than monthly log files, and WPDT’s cleanup operations target only monthly log files. Recording files are not affected by age-based cleanup, size-based cleanup, or the Clear Logs action. They persist until you delete them manually.
Query log files store encrypted JSON data for every captured SQL query, including full backtrace data and component attribution. A single recording session on a complex page load generates significantly more data than a comparable set of error log entries. The 100 MB default accounts for that density difference. Lower it if disk space is a concern, or raise it if you need to retain longer historical recordings.
The dbtk_daily_log_cleanup action depends on WordPress cron, which only fires when visitors load pages. On low-traffic sites, cleanup may run late. To ensure reliable scheduling, configure a system-level cron job to trigger WordPress cron on a fixed schedule. See WordPress Error Log Rotation and Retention for a WP-CLI cron example.
Always-On Logging Mode – Understand how persistent query logging generates data before you decide on retention thresholds.
WordPress Error Log Rotation and Retention – The same Log Cleanup tab also manages error log retention. See how the two systems compare and configure both from one place.
Recording WordPress Database Queries – Use time-limited recording sessions to capture smaller, more targeted query log files that are easier to keep within your retention limits.
