Improve the Logger functionality to reduce the size of the log file

[girlie]

Describe the bug
Certain Logger functions have the potential to generate a large amount of output into the wp-rocket-debug.log.html file, which becomes difficult (if not impossible) to open, read, search, etc., and can even take some sites down. (This is why I filed this as a bug rather than an enhancement.)

For example, this code for logging the replacement of CSS images with the lazyloaded version writes the entire HTML output from the page being processed into the log:

wp-rocket/inc/Engine/Media/Lazyload/CSS/Subscriber.php

Line 167 in 3c046b5

$this->logger::debug(

So it's much like having every cache file all merged together in a single file, and then some. (I have one case where each cache file is 1.5MB or larger, and with approximately 800 URLs to be processed, that would mean a minimum size of 1.2GB for the log file by the time it's all done.)

Other possibilities for further refinement/reconsideration:

• DEBUG: Found XX <link> tags
• NOTICE: Skipped URL
• NOTICE: Extracted Content

It seems most of us probably use this file to diagnose wpr not cached issues; so as listed by Camila, we're mostly looking at the logger entries for:

• donotcachepage set
• buffer content under 255
• excluded or mandatory cookie
• config file not found

Most of the above was extracted from this Slack thread: https://group-onecom.slack.com/archives/C08EFUD9XLJ/p1743007363049459

[alfonso100]

This is important, as the current status of the WP_ROCKET_DEBUG makes it risky because the log file will grow very fast, breaking the WP Rocket UI and potentially filling the server space

related issue:
#6618

[joejoe04]

Related:
https://group-onecom.slack.com/archives/C08EFCZ68NP/p1748363910537829?thread_ts=1748363066.217769&cid=C08EFCZ68NP
https://secure.helpscout.net/conversation/2950035398/563059

[camilamadronero]

Rocket Care customer: https://secure.helpscout.net/conversation/2951101774/563312

Issue: Due to the site traffic (Preload was off), the log file kept growing to the point where the server became irresponsive. This highly impacted the Rocket Care installation process and the customer experience since we crashed their server 😥

[alfonso100]

From a Support perspective, reducing the noise of WP_ROCKET_DEBUG would be a big win.

To Remove from the log
These are some examples of logs that are not critical for most support/debugging cases:

• RUCSS & Rocket Insights queue processing logs (e.g. "start processing", "submit jobs", "jobs found", etc.)
• Minification info logs should only be kept on errors, remove all the informative entries like:
  -- Found X tags
  -- Minified CSS file successfully created
  -- Style minification succeeded
• "LazyLoad" ending log entries that include the full HTML.
• Any big chunk of HTML
• Repeated messages like:
  -- CACHING PROCESS STARTED, OPTIMIZATION PROCESS STARTED. PHP, XML or XSL file is excluded when referring to admin-ajax.php or wp-cron.php

Suggestion:

• WP_ROCKET_DEBUG should deliver the lean version of the log
• we can introduce a secondary constant, e.g., WP_ROCKET_DEBUG_ADVANCED, to explicitly enable verbose/noisy logs as it is now.

Some possible enhancements:

• make it easier to detect the homepage request_uri: / <--- homepage
• a way to limit the log only if a specific URL is visited. Super helpful for us to troubleshoot specific issues. For example, we can add a URL instead of true, it enables the log for a specific URL:
  -- define( 'WP_ROCKET_DEBUG', 'https://wphangar.com/sample-page' );

For context, in Support, as @girlie and @camilamadronero mentioned, we mostly rely on this log to understand why a page is not cached, and anything that generates large volumes of repetitive or expected entries makes these key signals very hard to find.

These are important for us:

• donotcachepage detected
• Buffer content under 255
• Excluded cookies found
• Config file not found
• Query strings preventing cache

[Miraeld]

I initially considered adding a WP_ROCKET_DEBUG_ADVANCED constant to control verbose logging, but this would create confusion around which constant to use for what purpose. Instead, I've been thinking of making the existing WP_ROCKET_DEBUG constant smarter by allowing it to accept a URL string to limit logging to only that specific page. This approach is simpler, more intuitive for the support team, and maintains backward compatibility.

Scope a solution

Update inc/Logger/Logger.php:

• Modify debug_enabled() to accept both true (current behavior) and URL strings
• Add should_log_current_url() method to match current request against debug URL
• Add normalize_url() helper to handle trailing slashes, query strings, and case differences

Acceptance Criteria

• WP_ROCKET_DEBUG = true logs everything (backward compatible)
• WP_ROCKET_DEBUG = 'https://example.com/page' logs only that URL
• WP_ROCKET_DEBUG = '/page' works with relative paths
• URL matching ignores trailing slashes, query strings, and is case-insensitive
• Homepage can be matched with / or full URL

[joejoe04]

Thank you @Miraeld! I love the idea of limiting the logging to specific pages.

The support team, (@webtrainingwheels in particular) had some points of feedback so far:

1️⃣ Could there be an option to submit an array so multiple pages can be logged? Something like:
WP_ROCKET_DEBUG = [ '/page1/', /page-2/', '/page-3/' ]

2️⃣ While limiting logging to just specific pages is nice, it could still lead to the log file size ballooning too big if left in place. Additionally, users could still add the regular log without limiting pages as well.

Would it be possible to also set some kind of file size limit and stop any logging once it reaches a certain size?

3️⃣ One last point is that there is still some output from the logs that are not useful at all and really clutter the logs. One example in particular is this point from @girlie :

the code for logging the replacement of CSS images with the lazyloaded version writes the entire HTML output from the page being processed into the log

Thank you! 🙏

[DahmaniAdame]

Discussing with support their needs to define acceptance criteria.

[Miraeld]

@joejoe04 about your point 3, we got #6618

[alfonso100]

thanks @Miraeld about the acceptance criteria, we are working on it here:
https://group-onecom.slack.com/archives/C08EFUD9XLJ/p1767971648670149?thread_ts=1767971544.714349&cid=C08EFUD9XLJ

Can you please check that list so we can update the current one here? thanks!

[alfonso100]

@DahmaniAdame / @Miraeld

Acceptance Criteria

1. Default log is as lean as possible
When WP_ROCKET_DEBUG is enabled, the log must not include:

• Full HTML output or large content blocks. No single log entry may exceed a reasonable size limit (e.g. no full HTML dumps).
  Informational / repetitive logs from:
• RUCSS and Rocket Insights queue processing informational messages
• Minification success messages (e.g. “Found X tags”, “Minified CSS successfully created”)
• LazyLoad logs that dump processed HTMLRepeated “process started / file excluded” messages for expected exclusions (e.g. admin-ajax.php, wp-cron.php)
• The log file remains readable and searchable even on large sites.

2. Critical logs are preserved
The following entries must always be logged when WP_ROCKET_DEBUG is enabled:

• donotcachepage detected
• Buffer content under 255 bytes
• Excluded or mandatory cookies detected
• Config file not found
• Query strings preventing cache
• Database error related messages: e,g. The group "rocket-rucss" does not exist.

3. Limit logging to specific URLs
Implement a URL-scoped debug mode:

• accept single URLs and multiple URLs (array)
• Logging is only produced for the specified URLs
• Other requests generate no debug output.

4. Document code changes
For any new hooks or functional changes, include a short, human-readable summary for Support. Add a minimal code example if needed. This content may be reused by Support and Docs.