Database Monitor overview

WP Debug Toolkit (WPDT) tracks every database query WordPress executes on each page load. Queries are logged to encrypted files on the filesystem — not to the database — so monitoring does not add database overhead or affect the performance you are measuring.

What it tracks

The Database Monitor captures every SQL query that runs through the WordPress wpdb class during a request. For each query, it records:

• The SQL statement
• Execution time (in milliseconds)
• Whether the query is slow, duplicated, or produced an error
• The HTTP request that triggered it (URL, method, timestamp)

With enhanced logging enabled (via the db.php drop-in), it also captures:

• Full PHP backtrace (the chain of function calls that led to the query)
• Component attribution (which plugin, theme, or core subsystem triggered it)
• Caller function (the specific method or function that ran the query)

Filesystem-based logging

WPDT writes query data to log files in wp-content/uploads/debug-toolkit/queries/, organized by month (queries-2026-03.log). This filesystem-based approach has a key advantage over tools that store query data in the database or in PHP memory: it does not alter what you are measuring.

This is the “zero Observer Effect” principle. Database-backed monitoring tools add their own queries to the results. Memory-backed tools inflate peak memory usage. WPDT writes to flat files, so the queries you see in the log are the queries your site actually runs, nothing more.

Encryption at rest

All query log entries are encrypted before being written to disk. Each line in the log file starts with the DBTKQ1: prefix, followed by the encrypted payload. WPDT uses libsodium when available, falling back to AES-256-GCM via OpenSSL. The encryption key is generated automatically and stored in the WordPress database, then synced to the standalone viewer’s config.php during setup.

Plaintext query data (SQL statements, backtraces, component names) never touches the filesystem unencrypted.

Basic vs enhanced logging

WPDT supports two logging modes. The difference comes down to whether the db.php drop-in is installed.

Basic logging gives you SQL, timing, and partial backtrace/component data parsed from the SAVEQUERIES stack trace. Enhanced logging provides full, structured backtraces with precise component attribution and caller identification.

The db.php drop-in

WordPress supports a database drop-in file at wp-content/db.php. When present, WordPress loads it instead of its default database class. WPDT’s drop-in extends the wpdb class with a custom DBTK_DB class that captures a debug_backtrace() before each query executes, then passes it along with the query results to the logging system.

The drop-in installs automatically when you enable enhanced query logging from the admin dashboard or via wp dbtk query-log enable. It is removed when you disable enhanced logging. See The db.php drop-in for details on conflicts and troubleshooting.

Recording vs always-on logging

The Database Monitor supports two approaches to query logging:

Recording (recommended for most use cases) — Start a time-limited recording from the admin dashboard. Queries are captured only during the recording window (10 seconds to 1 hour). This avoids the disk I/O overhead of continuous logging. Use recordings to debug a specific page load, checkout flow, or admin operation. See Query recording and shareable URLs.

Always-on logging — A developer override that logs every query on every request. This generates significant disk writes on active sites and is not recommended for production or high-traffic environments. Enable it from the admin dashboard under the Database Monitor card, where a performance warning is shown before activation. Always-on logging is intended for development environments where you want continuous visibility.

For most sites, recording is the right choice. Start a recording, reproduce the behavior you want to inspect, then review the captured queries in the Query Viewer.

Requirements

• Query module license — the Database Monitor is part of the Query module (included in Pro)
• Query logging enabled — toggle from Debug Toolkit > Overview or run wp dbtk query-log enable
• Standalone viewer installed — the Query Viewer interface lives in the standalone viewer
• Enhanced logging recommended — basic mode works, but backtraces and component attribution require the db.php drop-in

Comparison with Query Monitor plugin

The Query Monitor plugin by John Blackbourn is a well-known tool for inspecting WordPress queries. WPDT takes a different approach:

The two tools solve different problems. Query Monitor plugin is built for real-time, per-request inspection from the admin bar. WPDT is built for persistent logging, historical analysis, and debugging, even when WordPress itself is unavailable.