Skip to content
Gravity Tables
minor v3.2.0 · · 2 min read

Production-grade debugging, `?gt_debug=1` on any page

A custom logging system, real-time admin log viewer, and URL-activated debug mode for live sites. Diagnose problems on production without screen-sharing with a customer.

  • File-based debug logging independent of WordPress' debug.log
  • Admin log viewer with color-coded entries, download, and clear actions
  • URL-based debug activation: append `?gt_debug=1` to any page
  • Cache-busting diagnostics with direct DB queries to detect inconsistencies
  • Safe logging wrapper, logging failures never break AJAX

If you’ve ever asked a client “can you turn on WP_DEBUG?”, you know the answer is no. Either they don’t know what that is, or they’re afraid to edit wp-config.php, or their hosting doesn’t allow file edits, or all three.

3.2 ships a debug system that doesn’t ask anyone to touch wp-config.php.

URL-activated debug#

Any page on any Gravity Tables installation can be debugged by appending ?gt_debug=1 to the URL. The plugin:

  1. Detects the parameter
  2. Verifies the current user has manage_options capability (no public exposure)
  3. Activates verbose logging for the page render
  4. Renders an admin-only debug panel inline with the table

No wp-config.php edit. No SFTP. No “can you turn on debug?” emails.

Why a custom log#

WordPress has debug.log. We considered just using it. Two reasons we didn’t:

  1. It’s all-or-nothing. Turning on WP_DEBUG_LOG floods the file with noise from every plugin and theme. Finding our entries means grep, and grep across 100MB of log churn is slow.
  2. It requires file write permissions on a path that hosts often lock down.

The new gt-debug.log lives in wp-content/uploads/gt-logs/ (a path WP requires to be writable anyway), is rotated daily, and contains only Gravity Tables entries. The admin viewer reads from it directly with proper capability checks.

The admin log viewer#

Found at Tables → System → Debug Log:

  • Color-coded levels (info / warn / error / critical)
  • Filter by date, level, or table
  • Download the current log as .log
  • Clear log button (audited, requires confirmation)
  • Tail-follow mode that polls every 2 seconds

It’s a small operations dashboard built into the plugin. Not glamorous, but the kind of thing that turns “can you reproduce this?” into “here, send me the log”.

Safe logging wrapper#

Every internal logging call is wrapped in a try/catch. If the log file is unwritable, the logging silently no-ops. This sounds like a small detail, it eliminates a class of bugs where the act of trying to log an error caused a worse error.

What this enabled#

3.2 was the foundation for 3.4’s customer-friendly license activation (release notes) and 4.0’s Thickbox integration. Both of those features touched a lot of code paths; both of them were debuggable on customer sites without us asking customers to edit anything.

Without 3.2, debugging frontend-editing edge cases would have meant painful screen-share sessions. With 3.2, customers email us a log file. Issue identified, often fixed inside an hour.

What’s still on the todo list#

  • Sentry integration for opt-in remote error reporting (privacy-respecting, off by default)
  • Per-table debug mode, narrow logging to only one table on busy sites
  • JSON log format for programmatic ingestion

These are queued for the 4.2 line.

#debugging#observability#production