Wp Performance

WP Performance (backend-only)

When to use

Use this skill when:

• a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
• you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
• you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls

This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.

Inputs required

• Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
• How to target the install:
• WP root --path=<path>
• (multisite/site targeting) --url=<url>
• The performance symptom and scope:
• which URL/REST route/admin screen
• when it happens (always vs sporadic; logged-in vs logged-out)

Procedure

0) Guardrails: measure first, avoid risky ops

1. Confirm whether you may run write operations (plugin installs, config changes, cache flush). 2. Pick a reproducible target (URL or REST route) and capture a baseline:

• TTFB/time with curl if possible
• WP-CLI profiling if available

Read:

• references/measurement.md

1) Generate a backend-only performance report (deterministic)

Run:

• node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]

This detects:

• WP-CLI availability and core version
• whether wp doctor / wp profile are available
• autoloaded options size (if possible)
• object-cache drop-in presence

2) Fast wins: run diagnostics before deep profiling

If you have WP-CLI access, prefer:

• wp doctor check

It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).

Read:

• references/wp-cli-doctor.md

3) Deep profiling (no browser required)

Preferred order:

1. wp profile stage to see where time goes (bootstrap/main_query/template). 2. wp profile hook (optionally with --url=) to find slow hooks/callbacks. 3. wp profile eval for targeted code paths.

Read:

• references/wp-cli-profile.md

4) Query Monitor (backend-only usage)

Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and _envelope responses:

• Authenticate (nonce or Application Password).
• Request REST responses and inspect headers (x-qm-*) and/or the qm property when using ?_envelope.

Read:

• references/query-monitor-headless.md

5) Fix by category (choose the dominant bottleneck)

Use the profile output to pick one primary bottleneck category:

• DB queries → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
• references/database.md
• Autoloaded options → identify the biggest autoloaded options and stop autoloading large blobs.
• references/autoload-options.md
• Object cache misses → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
• references/object-cache.md
• Remote HTTP calls → add timeouts, caching, batching; avoid calling remote APIs on every request.
• references/http-api.md
• Cron → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
• references/cron.md

6) Verify (repeat the same measurement)

• Re-run the same wp profile / wp doctor / REST request.
• Confirm the performance delta and that behavior is unchanged.
• If the fix is risky, ship behind a feature flag or staged rollout when possible.

WordPress 6.9 performance improvements

Be aware of these 6.9 changes when profiling:

On-demand CSS for classic themes:

• Classic themes now get on-demand CSS loading (previously only block themes had this).
• Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
• If you're profiling a classic theme, this should already be helping.

Block themes with no render-blocking resources:

• Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
• Styles come from global styles (theme.json) and separate block styles, all inlined.
• This significantly improves LCP (Largest Contentful Paint).

Inline CSS limit increased:

• The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.

Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/

Verification

• Baseline vs after numbers are captured (same environment, same URL/route).
• wp doctor check is clean (or improved) when applicable.
• No new PHP errors or warnings in logs.
• No cache flush is required for correctness (cache flush should be last resort).

Failure modes / debugging

• “No change” after code changes:
• you measured a different URL/site (--url mismatch), caches masked results, or opcode cache is stale
• Profiling data is noisy:
• eliminate background tasks, test with warmed caches, run multiple samples
• SAVEQUERIES/Query Monitor causes overhead:
• don’t run in production unless explicitly approved

Escalation

• If this is production and you don’t have explicit approval, do not:
• install plugins, enable SAVEQUERIES, run load tests, or flush caches during traffic
• If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

Autoloaded options

Autoloaded options are loaded on every request, so large autoload payloads can hurt performance site-wide.

Quick checks

• Total autoload bytes:
• wp option list --autoload=on --format=total_bytes
• Find biggest autoloaded options:
• wp option list --autoload=on --fields=option_name,size_bytes | sort -n -k 2 | tail

Docs:

• wp option list: https://wpcli.dev/docs/option/list
• wp doctor includes an autoload-options-size check:
• https://make.wordpress.org/cli/handbook/doctor-default-checks/

Fix patterns

• Stop autoloading large blobs:
• store large data in non-autoload options (autoload=off)
• move large computed data to transients/object cache
• Remove stale options left behind by removed plugins/themes (careful: confirm usage before deleting).

WP-Cron performance

Use this file when cron causes spikes or request-time slowness.

Backend-only tools:

• wp cron test (spawning health)
• wp cron event list
• wp cron event run --due-now

Reference:

• WP-CLI cron command package: https://github.com/wp-cli/cron-command

Fix patterns:

• De-duplicate scheduled events and reduce frequency where possible.
• Ensure tasks are idempotent and short.
• Move heavy work off-request; cron that runs on page load can hurt TTFB.

Database / query performance

Use this file when profiling points to DB time or high query counts.

Common fixes:

• Avoid N+1 query patterns (batch queries, prime caches, avoid per-row lookups).
• Prefer fields => 'ids' when you only need IDs.
• Avoid expensive meta queries where possible; consider indexing or schema changes.
• Use object caching for repeated reads.

Tools (backend-only):

• Query Monitor (REST headers/envelope) for query lists and stack traces.
• wp db query for targeted SQL/explain (be careful in prod).

References:

• Query Monitor plugin: https://wordpress.org/plugins/query-monitor/

HTTP API (remote requests)

Use this file when profiling shows slow external requests (wp_remote_get, etc.).

Fix patterns:

• Add timeouts and fail-fast behavior.
• Cache responses where appropriate (transients/object cache).
• Batch requests and avoid calling remote APIs on every page load.
• Move heavy remote work to async (cron/queue) where possible.

Tooling:

• Query Monitor can report HTTP API calls (including timing) via REST envelope info.

Measurement (profiling vs benchmarking)

Backend-only measurement options:

• WP-CLI profiling (wp profile): best for pinpointing slow hooks/stages without a browser.
• WP-CLI doctor (wp doctor): best for quick diagnostics (autoload bloat, debug constants, updates).
• Query Monitor via REST: use authenticated REST requests and inspect x-qm-* headers / qm envelope data.
• Server-Timing (Performance Lab): inspect Server-Timing headers via curl -I (when enabled).
• APM/profilers: New Relic, Datadog, Blackfire, Tideways, XHProf/Xdebug (requires server support).

Best practices:

• Always capture a baseline first.
• Keep the test scenario fixed (same URL/route, same user state, same data).
• Prefer multiple samples and medians over single runs.

References:

• Measuring performance handbook: https://make.wordpress.org/performance/handbook/measuring-performance/
• Benchmarking with Server-Timing: https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/

Object caching

Use this file when profiling indicates repeated queries or low cache hit rate.

Concepts

• Default WP object cache is per-request memory only.
• A persistent object cache “drop-in” (wp-content/object-cache.php) can persist cache across requests.

WP-CLI cache commands:

• https://wpcli.dev/docs/cache

Guardrails:

• wp cache flush can impact all sites in multisite and cause load spikes:
• https://wpcli.dev/docs/cache/flush

Fix patterns

• Cache expensive computed results (transients or object cache) with explicit invalidation.
• Avoid unbounded caches (set expirations or implement invalidation hooks).
• If adding a persistent object cache, coordinate with infra (Redis/Memcached) and test cache flush behavior.

Query Monitor (headless / backend-only)

Query Monitor is UI-first, but it can expose useful data to backend-only tooling.

What it can show

Query Monitor can help debug:

• DB queries (slow/dupes/errors), hooks/actions, HTTP API calls, PHP errors

Plugin page:

• https://wordpress.org/plugins/query-monitor/

Configuration constants:

• https://querymonitor.com/help/configuration-constants/

REST API requests (no browser needed)

Query Monitor can add performance/error info to authenticated REST responses.

Docs:

• https://querymonitor.com/wordpress-debugging/rest-api-requests/

High-level approach:

1. Authenticate (nonce or Application Password). 2. Make a REST request and inspect response headers like x-qm-overview-*. 3. If you request an enveloped response (?_envelope), you can get a qm property with:

• DB queries details, cache stats, HTTP API request details, etc.

Guardrails

• Query Monitor adds some overhead; don’t enable it in production without approval.
• If it’s already installed by your platform (e.g. VIP), you may need to grant view_query_monitor.

Server-Timing (Performance Lab)

Use this file when you can enable Server-Timing metrics and want backend-only inspection via HTTP headers.

Performance Lab plugin:

• https://wordpress.org/plugins/performance-lab/

Benchmarking guidance:

• https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/

Backend-only approach:

• Enable the relevant module/standalone plugin.
• Request a URL and inspect the Server-Timing header:
• curl -sS -D - https://example.test/ -o /dev/null | rg -i \"^server-timing:\"

Guardrails:

• Don’t enable experimental modules in production without approval.

WP-CLI doctor (wp doctor)

Use this for quick “production readiness” checks.

Install (if missing)

• wp package install wp-cli/doctor-command

Docs:

• Default checks: https://make.wordpress.org/cli/handbook/doctor-default-checks/
• Customize checks: https://make.wordpress.org/cli/handbook/guides/doctor/doctor-customize-config/

Recommended usage

• wp doctor check
• wp doctor list (to see available checks)

Especially relevant to performance:

• autoload-options-size (autoloaded options threshold)
• constant-savequeries-falsy / constant-wp-debug-falsy (avoid perf-costly debug flags in prod)
• cron checks (count/duplicates)

WP-CLI profiling (wp profile)

Use this when you need actionable profiling without a browser.

Install (if missing)

wp profile comes from a WP-CLI package:

• wp package install wp-cli/profile-command

Docs:

• https://wpcli.dev/docs/profile/stage
• https://wpcli.dev/docs/profile/hook
• https://wpcli.dev/docs/profile/eval

Recommended sequence

1. Stage overview:

• wp profile stage --fields=stage,time,cache_ratio [--url=<url>]

2. Hooks hotspot:

• wp profile hook --spotlight [--url=<url>]
• then drill into a specific hook:
• wp profile hook init --spotlight [--url=<url>]

3. Targeted evaluation:

• wp profile eval 'do_action(\"init\");' --hook=init

Tips:

• Use --url to profile specific site/route behavior.
• Use --skip-plugins / --skip-themes to isolate culprit components (careful: behavior changes).