Reading PMP Debug Logs #
PetMatchPro writes structured entries to your WordPress debug log so you can diagnose API failures, verify field exclusions, audit deactivations, and trace any other plugin event. This article shows you how to enable debug logging, where the log lives, and what the entries mean.
Enabling Debug Logging #
Debug logging is controlled by two constants in your wp-config.php file:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );WP_DEBUG– turns on PHP error reporting and lowers PetMatchPro’s log threshold so DEBUG-level entries are emitted.WP_DEBUG_LOG– tells WordPress to write log output towp-content/debug.loginstead of (or in addition to) PHP’s default error log destination.WP_DEBUG_DISPLAY– should befalseon any site that real visitors can reach. When true, errors render as text on the page and break redirects after activation.
If WP_DEBUG_LOG is not defined but WP_DEBUG is, PetMatchPro still emits entries – they just go to your hosting provider’s PHP error log path instead of wp-content/debug.log.
Locating the Log File #
With WP_DEBUG_LOG set to true, the log file lives at:
wp-content/debug.logIf you set WP_DEBUG_LOG to a path string instead of true, the log writes to that path. If WP_DEBUG_LOG is unset, check your hosting control panel for the PHP error log location (cPanel and most managed hosts surface this in the Logs section).
Entry Format #
Every PetMatchPro log entry follows this structure:
[request-utc-time] [PetMatchPro] [iso-utc-time] [LEVEL] Subsystem: message | Context: {structured-data}Concrete example from a deactivation:
[08-May-2026 15:14:22 UTC] [PetMatchPro] [2026-05-08 15:14:22] [WARNING] Deactivator: deactivated at 2026-05-08 11:14:22And from a broken-API-key search:
[08-May-2026 15:24:01 UTC] [PetMatchPro] [2026-05-08 15:24:01] [ERROR] AllApi: PetPoint: HTTP 401 from PetPoint API | Context: {"http_code":401,"method":"AdoptableSearch","response_excerpt":"<html><head><title>Unauthorized</title>..."}Field-by-field:
| Field | Meaning |
|---|---|
[utc-time] |
WordPress’s standard error_log timestamp prefix. |
[PetMatchPro] |
Plugin tag – lets you filter PMP entries from third-party plugin noise. |
[iso-utc-time] |
PetMatchPro’s own ISO timestamp – useful when entries arrive out of order due to multiple PHP workers. |
[LEVEL] |
Severity: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
Subsystem: |
Identifies which part of PetMatchPro emitted the entry. See the table below. |
Context: {...} |
Optional JSON-encoded structured data – HTTP code, animal IDs, file paths, etc. Sensitive keys (passwords, API keys) are filtered before logging. |
Subsystem Prefixes #
The Subsystem identifier is the most useful field for grepping. Common prefixes:
| Prefix | What it covers |
|---|---|
Admin: |
Admin-bootstrap events: i18n initialization, dependency loading. |
Admin Settings: |
Admin form save/load, settings registration. |
Admin Functions: |
Admin helper utilities. |
AllApi: |
Shared API logic – error message construction, license checks, parameter processing. Wraps lower-level partner-specific entries. |
Deactivator: |
Plugin deactivation and uninstall lifecycle. |
Color-CSS: |
Generated CSS file write failures. |
Field-Exclusion: |
Field-value exclusion engine (FieldExclusionFilterTrait), used by AnimalsFirst and RescueGroups search templates. |
PetPoint Field-Exclusion: |
PetPoint’s XML-level field exclusion (applied before the template renders). |
RG API: |
RescueGroups HTTP/JSON exchange details. |
Analytics AJAX: |
Analytics dashboard widget AJAX requests. |
SearchTemplate: / DetailTemplate: / PosterTemplate: |
Template-layer events. |
Celebration Template: |
AnimalsFirst celebration-similar template exception path. |
Filter-Override-Manager: |
Filter customization overrides. |
Partner-specific events from AllApi are also tagged in the message body (not the Subsystem prefix), e.g. AllApi: PetPoint: HTTP 401 from PetPoint API. Grep for the partner name to find them: grep "AllApi: PetPoint" debug.log.
Common Entries to Look For #
API Failures #
When a search or detail page renders the red error block, the matching log entries usually look like:
[ERROR] AllApi: PetPoint: HTTP 401 from PetPoint API | Context: {"http_code":401,"method":"AdoptableSearch","response_excerpt":"..."}
[ERROR] AllApi: AnimalsFirst: HTTP 401 from AnimalsFirst API | Context: {"http_code":401,"response_excerpt":"..."}
[ERROR] AllApi: RescueGroups: HTTP 401 from RescueGroups API | Context: {"http_code":401,"method":"publicAnimalsSearch","response_excerpt":"..."}The response_excerpt in Context is the first 200 characters of the partner’s response body – often enough to identify whether the response is a partner error page, a Cloudflare block, or something else entirely. See the partner integration guides for the full error taxonomy: PetPoint, AnimalsFirst, RescueGroups.
Field Exclusions #
If you’ve configured exclusions under General > Exclusions per method type, every search will emit:
[DEBUG] AllApi: Field-Exclusion: Field: location (fallback: site), Exclusions: morgue, holding
[DEBUG] AllApi: Field-Exclusion: EXCLUDED: ID=12345, Name=Buddy, location=Morgue (matched: morgue)
[DEBUG] AllApi: Field-Exclusion: Summary: 50 total, 3 excluded, 47 remaining(For PetPoint the prefix is PetPoint Field-Exclusion: instead, because PP applies exclusions at the XML layer rather than via the trait.)
If exclusions appear to “work” (excluded animals don’t show) but no log entries fire, that means the search results never contained the excluded values to begin with – the API didn’t return them, often because of search criteria or a partner-side filter.
Deactivation and Uninstall #
[WARNING] Deactivator: deactivated at 2026-05-08 11:14:22
[WARNING] Deactivator: completely uninstalled at 2026-05-08 11:14:22These fire on the canonical lifecycle events. If you only see one of them, the other phase didn’t run.
Invalid Color Save #
The Colors tab admin notice on bogus values doesn’t always log (it’s an admin-side validation result), but the matching audit can be inferred from the absence of new :root { --pmp-color-... } entries in the generated style file. See Color Customization > What Happens When You Save an Invalid Value.
Grep Recipes #
Useful one-liners (run from your site root or against the log file directly):
# All PMP entries
grep "\[PetMatchPro\]" wp-content/debug.log
# Errors only
grep "\[ERROR\] AllApi" wp-content/debug.log
# Authentication failures
grep "HTTP 401\|HTTP 403" wp-content/debug.log | grep "PetMatchPro"
# Field exclusion activity
grep "Field-Exclusion" wp-content/debug.log
# All entries from the last hour (Linux)
grep "$(date -u +%d-%b-%Y\ %H -d '1 hour ago')" wp-content/debug.log | grep "PetMatchPro"
# Deactivation history
grep "Deactivator" wp-content/debug.logLog Rotation #
WordPress doesn’t rotate debug.log automatically. On a busy site with WP_DEBUG enabled, the file can grow to gigabytes. Either:
- Disable WP_DEBUG_LOG once you’ve finished a debugging session, or
- Add a logrotate config (system-level on Linux/macOS) to rotate
wp-content/debug.logdaily or weekly.
For one-off cleanup: truncate -s 0 wp-content/debug.log empties the file in place without restarting the web server.
Related #
- wp-config.php Configuration Constants – other PMP-specific debugging toggles.
- API Connection Issues – diagnostic walkthrough when search results fail.
- Common Error Messages – what each public-facing error block means.
- How to Contact Support – what to send when you escalate.
