---
title: Reading PMP Debug Logs
description: 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…
url: "https://petmatchpro.com/docs/reading-debug-logs/"
updated: "2026-10-24"
category: Troubleshooting
---

# 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 to `wp-content/debug.log` instead of (or in addition to) PHP's default error log destination.
- **`WP_DEBUG_DISPLAY`** - *should be `false` on 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.log
```

If 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:22
```

And 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](/docs/petpoint-integration-guide/#error-messages), [AnimalsFirst](/docs/animalsfirst-integration-guide/#error-messages), [RescueGroups](/docs/rescuegroups-integration-guide/#error-messages).

### 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:22
```

These 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](/docs/color-customization/#invalid-values).

## 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.log
```

## Log 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.log` daily 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](https://petmatchpro.com/docs/wp-config-constants/) - other PMP-specific debugging toggles.
- [Performance Profiler](https://petmatchpro.com/docs/performance-profiler/) - log coarse server-side timings to find what makes a search page slow.
- [API Connection Issues](https://petmatchpro.com/docs/api-connection-issues/) - diagnostic walkthrough when search results fail.
- [Common Error Messages](https://petmatchpro.com/docs/common-error-messages/) - what each public-facing error block means.
- [How to Contact Support](https://petmatchpro.com/docs/how-to-contact-support/) - what to send when you escalate.

 Reading PMP Debug Logs ultima modifica:  2026-05-08T12:36:45-04:00 da PetMatchPro