Overview

The Core Web Vitals (CWV) Metrics module in ZiziCache provides real‑user monitoring (RUM) for key performance signals. It records LCP (Largest Contentful Paint), LoAF (Long Animation Frames), and optionally TTFB (Time to First Byte) and aggregates them for per‑URL analysis.

Where to Configure

1. Open ZiziCache → Metrics → CWV Metrics.
2. Enable monitoring and configure sampling and diagnostics.

Configuration Options (Admin UI)

Enable CWV Monitoring

Key: cwv_monitor_enabled

Master switch for the whole CWV module. When disabled, no CWV data is stored and CWV cron jobs are stopped.

Frontend Banner (Admin Only)

Key: cwv_banner_enabled

Shows a small frontend banner for logged‑in administrators. The banner combines live measurements from the Performance API with aggregated data from the database and links to the CWV Metrics page. Dismissal is stored in localStorage and suppressed for 24 hours by default.

Console Debug

Key: cwv_console_debug

Enables detailed DevTools logging and developer helpers. For LoAF, this exposes loafHelpers in the console (summary, top scripts, percentiles, layout‑thrashing diagnostics). For TTFB, it logs a timing breakdown table.

TTFB Monitoring

Key: cwv_ttfb_enabled

Collects server response timing using the Navigation Timing API. This is useful for cache efficiency analysis and backend bottleneck detection.

Sampling Rate

Key: cwv_sampling_rate

Controls what percentage of non‑admin visitors send CWV data. This reduces database load on high‑traffic sites. Sampling currently applies to LoAF and TTFB collectors. (LCP collection is driven by the LCP detector–see below.)

Recommended values (from the UI):

• Shared hosting: 0.1-0.5%
• VPS (1-2 CPU, 2-4 GB RAM): 0.5-1%
• VPS/Dedicated (4+ CPU, 8 GB+ RAM): 1-5%
• High traffic (100k+ visits/day): 0.1-1%

What Gets Collected

LCP (Largest Contentful Paint)

LCP metrics are collected by the LCP detector used in Image Optimization. It uses PerformanceObserver and sends the final LCP time plus element metadata (tag, selector, class, ID, src, size, fetch priority).

Important: LCP metrics require Automatic LCP Detection to be enabled in ZiziCache → Optimization → Image Optimization (img_auto_lcp), and CWV monitoring must be enabled (cwv_monitor_enabled).

LoAF (Long Animation Frames)

LoAF uses the long-animation-frame Performance Observer (supported in Chromium‑based browsers). It captures long tasks, script attribution, and forced layout time to identify layout thrashing. When Console Debug is enabled (or for admins), the console helpers provide actionable diagnosis.

TTFB (Time to First Byte)

TTFB uses Navigation Timing to compute response timing and attribution breakdown (DNS, TCP, SSL, request). It’s excellent for spotting backend and caching issues.

Storage & Retention

Metrics are stored in dedicated MySQL tables:

• {prefix}_zizi_cwv_metrics — raw CWV events
• {prefix}_zizi_cwv_summary — aggregated summaries

Aggregation runs every 5 minutes when monitoring is enabled (zizicache_cwv_aggregate). Cleanup runs daily (zizicache_cwv_cleanup) using retention settings.

Advanced Configuration (REST/API)

Advanced keys can be updated via POST /wp-json/zizi-cache/v1/config:

# Thresholds (ms)
cwv_lcp_threshold_ms        (default: 2500)
cwv_loaf_threshold_ms       (default: 150)
cwv_ttfb_threshold_ms       (default: 600)

# LoAF buffering
cwv_loaf_buffer_size        (default: 30)
cwv_loaf_flush_interval_ms  (default: 10000)

# Banner behavior
cwv_banner_suppression_hours (default: 24)
cwv_page_summary_cache_ttl   (default: 300 seconds)

# Data retention
cwv_store_raw_days           (default: 7)
cwv_summary_days             (default: 30)

# Payload limits
cwv_max_payload_size         (default: 24576 bytes)

Rate Limiting & Safety

The public /cwv/metrics endpoint is rate‑limited per IP + URL. Defaults are 60 seconds / 20 requests and can be adjusted via filters:

apply_filters('zizicache_cwv_rate_limit_window', 60)
apply_filters('zizicache_cwv_rate_limit', 20)

Admins and localhost environments are exempt.

Why This Matters (Benefits)

• Real‑world visibility: Collects actual user measurements, not lab estimates.
• Actionable diagnostics: LoAF identifies scripts with layout thrashing.
• Faster optimization cycles: LCP element details show the exact rendering bottleneck.
• Infrastructure insight: TTFB highlights server and cache health.

Troubleshooting

• No data: Ensure cwv_monitor_enabled is on and sampling is not 0. For LCP, enable img_auto_lcp in Image Optimization.
• LoAF missing: Only Chromium‑based browsers support long-animation-frame.
• Banner not showing: Must be logged in as admin, banner enabled, and not suppressed in localStorage.
• TTFB missing: Enable cwv_ttfb_enabled and test on a full page load.