Debug Documentation

SSP — Debugging (Docs)

SSP Documentation

SSP Debugging

Admin Screen

The plugin adds a menu item in your WordPress admin sidebar called SSP Debugging (tools icon). It opens a single dashboard where you configure logging and view the log file.

Controls

  • Enable logging — master on/off.
  • Level — All or Fatal-only.
  • Log format — Basic or Detailed (adds URL/IP/UA/User ID).
  • Size limit (MB) — auto-truncates to ~70% when exceeded.
  • Sources — include MU-plugins, Plugins, Themes, Core/Other.
  • Ignore list — one per line, substring or regex (/deprecated/i).
  • Timezone — Site default, UTC, or a fixed named zone.

Actions

  • Save Settings — applies changes immediately.
  • Clear Log — empties the file.
  • Download Log — downloads wp-content/ssp-debug.log.
Tip: Newest entries appear first in the viewer for quick triage.

Viewer

  • Shows the full log in a read-only textarea.
  • Displays file path and size above the viewer.
  • Use your browser find (Ctrl/Cmd-F) to search entries.

How It Works

  • Handlers: On load, the plugin installs a PHP error handler, exception handler, and shutdown handler. Messages are written to wp-content/ssp-debug.log.
  • Emergency capture: A small MU bootstrap also logs fatal shutdowns as early as possible, even if regular plugin code can’t run.
  • Filtering: Only entries from selected sources (MU-plugins/Plugins/Themes/Core) are written. Known success/info noise is suppressed. Your custom Ignore list is applied last.
  • Format: Each line starts with a timestamp (your chosen timezone). In Detailed mode, context is appended (URL, IP, User-Agent, User ID).
  • Rotation: When the file exceeds the size limit it is truncated down to about 70% to keep recent history.
  • Display: The admin viewer reverses the file in memory so newest entries are shown first; the on-disk file remains chronological.
Note: Detailed context is powerful for debugging but may include IP/UA/User ID. Use only when appropriate for your site’s policies.

Privacy & Data

  • Storage: All logs are written locally to wp-content/ssp-debug.log. Nothing is sent to third parties.
  • Scope: You control which code paths are logged (MU-plugins, Plugins, Themes, Core/Other) and which messages to ignore.
  • Personal data: In Basic format the line contains the message only. In Detailed format it adds request context (URL/IP/UA/User ID) for admin-only diagnostics.
  • Control: You can disable logging at any time, clear the file, or download it for support.

Troubleshooting

No entries appear
  • Confirm Enable logging is checked and click Save Settings.
  • Level may be set to Fatal-only (warnings/notices won’t log).
  • Your Sources might exclude where the error occurs.
  • An Ignore list pattern may be matching your message.
Log file not created / not updating
  • Ensure wp-content/ is writable by PHP.
  • Some hosts buffer writes; refresh after reproducing.
  • Conflicting error handlers from other plugins can interfere — try temporarily disabling them.
Timestamps look wrong

Pick a fixed timezone in settings or use Site default. Save and reproduce an error to see the new offset applied.

Log grows too fast
  • Lower the Size limit (MB) or switch to Fatal-only.
  • Add noisy messages or paths to the Ignore list.

Test / Verification

  1. Enable logging. Set Level to All and Format to Basic (or Detailed if desired).
  2. Create a temporary snippet (e.g., in a small test plugin) that runs: 
    add_action('init', function(){ trigger_error('SSP Debug test warning', E_USER_WARNING); });
  3. Visit any frontend page to trigger the warning.
  4. Open SSP Debugging → check the viewer: the new entry should appear at the top.
  5. Use Clear Log and verify the viewer empties; reproduce the warning and verify it returns.
Tip: To test fatal capture, temporarily throw an exception or call an undefined function in your test snippet, then remove it immediately after confirming the entry.