WP GraphQL WooCommerce Diagnostics

A diagnostic-only WordPress plugin for finding where slow WPGraphQL, WooGraphQL, and WooCommerce backend requests spend their time.

The plugin is built for headless WooCommerce storefronts where the frontend loads normally, but backend data operations such as add to bag, cart reads, checkout, customer, order, or related GraphQL calls can take several seconds. It captures privacy-conscious timing records inside WordPress so administrators can separate GraphQL execution time, WooCommerce behavior, database work, plugin/theme hook overhead, external HTTP calls, PHP runtime, memory use, and request-level errors.

Version: 0.1.2

What It Does

• Detects WPGraphQL and WooGraphQL requests.
• Assigns each captured request a unique diagnostic request ID.
• Records operation type, operation name when available, privacy-safe GraphQL root fields, route/context, duration, status, error presence, and WooCommerce relevance.
• Captures baseline request diagnostics when enabled.
• Provides administrator-controlled diagnostic windows for deeper tracing.
• Stores bounded diagnostic records with configurable retention.
• Shows dependency status for WooCommerce, WPGraphQL, and WooGraphQL in wp-admin.
• Provides a sortable and filterable diagnostics report in wp-admin.
• Shows request detail pages with timing breakdowns and trace availability notes.
• Exports diagnostic records as JSON or CSV.
• Clears retained diagnostic records from wp-admin.
• Optionally emits browser-visible correlation data through X-WPGWCD-Request-ID and compact Server-Timing headers.

What It Does Not Do

• It does not change WooCommerce, WordPress, plugin, theme, cache, database, hosting, or storefront behavior.
• It does not require Next.js or frontend code changes for v1.
• It does not automatically fix performance issues.
• It does not store raw customer, cart, checkout, authentication, or token payloads by default.
• It is not a full APM replacement or generic WordPress health-check plugin.
• It does not keep heavy profiling on permanently; deep tracing is limited to explicit diagnostic windows.

Requirements

• WordPress with administrator access.
• WooCommerce.
• WPGraphQL.
• WooGraphQL.
• PHP version compatible with your current WordPress and WooCommerce stack.

The plugin is intended for the latest stable versions of WordPress, WooCommerce, WPGraphQL, and WooGraphQL. It degrades gracefully when specific timing attribution is unavailable in the installed stack.

Installation

1. Copy this repository into your WordPress plugins directory as:

   wp-content/plugins/wp-graphql-woocommerce-diagnostics/
   

2. Activate WP GraphQL WooCommerce Diagnostics in Plugins.

3. Open Settings > GraphQL Diagnostics.

4. Confirm WooCommerce, WPGraphQL, and WooGraphQL dependency status.

5. Enable diagnostics and save settings.

Basic Workflow

1. Enable diagnostics in Settings > GraphQL Diagnostics.
2. Reproduce the slow storefront action, such as add to bag, cart read, checkout step, customer query, or order-related GraphQL request.
3. Open Diagnostics Report from the plugin settings page.
4. Filter by time, operation type, operation name, duration, error status, WooCommerce relevance, trace availability, or request ID.
5. Open a request detail page to review timing categories and likely bottleneck classification.

Baseline diagnostics are designed to stay lightweight. Use a diagnostic window only when deeper trace data is needed.

Diagnostic Windows

Diagnostic windows enable deeper profiling for a short, bounded period. They can capture additional timing for:

• Total PHP handling time.
• GraphQL execution time when available.
• Database query count and total query time when available.
• WordPress, plugin, theme, and WooCommerce hook timing buckets where feasible.
• External HTTP call count and total time when available.
• Peak PHP memory.

Diagnostic windows expire automatically, can be stopped manually, and enforce a trace cap to prevent unbounded storage growth.

Admin Report

The diagnostics report includes:

• Sortable request list.
• Filters for date/time, operation name, operation type, minimum duration, error status, WooCommerce relevance, trace availability, and request ID lookup.
• Request detail pages with baseline metadata, timing breakdowns, availability labels, cautious bottleneck classification, trace summaries, and capped/unavailable notes.
• JSON and CSV export actions.
• Clear diagnostics action.

Developer Correlation Headers

When developer correlation headers are enabled, GraphQL HTTP responses may include:

• X-WPGWCD-Request-ID: request ID that can be searched in the wp-admin diagnostics report.
• Server-Timing: compact timing metrics for browser devtools.

Headers are emitted only when developer mode is enabled and WordPress can still send response headers.

Privacy And Safety

This plugin is diagnostic-only. It is designed to help administrators inspect backend latency without mutating production behavior.

By default, diagnostic records avoid or redact sensitive customer, cart, checkout, authentication, and token data. Exports include diagnostic metadata and timing summaries rather than raw commerce payloads.

Access to settings, reports, exports, clearing records, and diagnostic windows is restricted to administrators with manage_options.

Known Limitations

• Real installed-stack browser UAT is still required for current WordPress, WooCommerce, WPGraphQL, and WooGraphQL combinations to confirm the developer correlation headers appear exactly as expected in browser Network tools.
• Validation-only GraphQL failures that bypass normal graphql_execute handling need runtime confirmation in a live WPGraphQL install.
• Resolver-level field-path timing and specific plugin/theme callback attribution are not part of v1.
• Timing attribution can be approximate or unavailable depending on the installed stack and which hooks fire during a request.

Public Release Checklist

Before publishing a release zip:

1. Install the plugin on a staging WordPress site running WooCommerce, WPGraphQL, and WooGraphQL.
2. Activate the plugin and verify dependency statuses in Settings > GraphQL Diagnostics.
3. Enable diagnostics and run at least one GraphQL query and one WooCommerce-relevant mutation.
4. Confirm retained records appear in Diagnostics Report.
5. Start a short diagnostic window and confirm deep trace availability appears for captured requests.
6. Enable developer correlation headers and confirm X-WPGWCD-Request-ID and Server-Timing in browser devtools.
7. Paste the request ID into the report lookup and confirm it opens the matching diagnostic record.
8. Export JSON and CSV.
9. Clear diagnostics and confirm retained records are removed.

Development Notes

The repository currently uses a lightweight PHP test harness under tests/ with WordPress function stubs rather than a full WordPress integration test environment.

Important source areas:

• wp-graphql-woocommerce-diagnostics.php: plugin entry point and activation hook.
• src/Plugin.php: runtime bootstrap.
• src/Admin/SettingsPage.php: settings page, diagnostic window controls, and admin actions.
• src/Admin/AdminReport.php: diagnostics report, filters, detail view, exports, and clearing.
• src/Capture/: GraphQL request capture, trace collection, request context, and developer correlation.
• src/Storage/: database schema and repositories.
• src/Reporting/: report query and bottleneck classification.

License

GPL-2.0-or-later. See LICENSE.