RFC: Performance and Logging in Headless WordPress Applications

[colinmurphy]

Title: Performance and Logging in Headless WordPress Applications
Author: Colin Murphy
Status: Draft
Created: May 2nd, 2025
Last Updated: July 21st, 2025

Abstract

In the context of headless WordPress (HWP) development, performance can be one of the key factors for using headless but it can also be of the most difficult parts of headless applications when you have performance issues and bottlenecks.

The difficulty of debugging performance can be due to a variety of factors such as knowing what the next steps are, where to debug and how to identify the performance bottlenecks (e.g. inefficient GraphQL queries, not using paginated queries etc).

Additionally sometimes these issues only replicable on a initial uncached request or a preview request and there can be difficulty tracing these requests and correlating your frontend and backend requests to help identify performance issues of your HWP application.

Motivation

Our motivation is to help HWP developers identify key performance issues at the earliest stage possible and also give them the resources and tools to resolve these issues in a timely fashion as possible when they do run into performance issues. We also want to give developers knowledge on key concepts around performance for HWP applications so they can learn best practices and avoid these pitfalls when building or maintaining a HWP application.

HWP applications are all unique and additionally can be complex in terms of setup so therefore when there are performance issues it can be hard to determine the root cause of issue, additionally there can be be multiple issues which can make it hard to debug and resolve. This can lead to frustration for a developer and also have a negative UI/UX experience for the user on the frontend of the application.

Our aim is to help alleviate these pain points by supplying relevant documentation around performance (such as best practices, debug help guides) and tools to analyze the performance of your headless application as the first steps.

Research

The RFC title is "Performance and Logging in Headless WordPress Applications" but seen realized from our research that this RFC would not be a finished piece but rather a long term incremental approach to helping developers with performance and logging in a HWP application.

The reason why is after reviewing Faust.js which we maintain and the HWP ecosystem along with having conversations with our community, we realized there was a clear initial list of first steps and "Logging" would need to be another step in our journey for this RFC.

Our first steps are based around "How does a HWP developer know how to debug their HWP application or how do they know what are the best practices when building their HWP application?" which is around the theme of "observability" and documentation.

Proposal

So the first initial phase of work we aim to cover three key areas:

1. Documentation - (Help guides, best practices, performance reference all leading to a HWP developer understanding how to debug and best practices)
2. Profiling Tool - Being able to profile your frontend application and get visibility of the performance of your application.
3. Tracing package - Being able to compare frontend and backend requests when debugging performance issues.

These three areas centre around the idea of "observability". If a HWP developer can observe and know how to debug their application, then they are able to make informed decisions on the next steps. We can build on this in later steps with tools/plugins to give more detailed analysis and recommendations for performance and logging.

Note

We also want to continue to contribute to WPGraphQL and other HWP plugins to help improve performance and promote the Headless WordPress ecosystem.

Future Considerations

As part of the research we also did review Jason Bahl's RFC wp-graphql/wp-graphql#3292 and we will collaborate with Jason on helping building a logging plugin for WPGraphQL. However we felt at this time that we wanted to focus in on helping HWP developers with better documentation and tools for observability as the first step with logging being the next step to follow straight after.

Other considerations after this point would be further enhancing the profiling tool with being able to sync backend requests to the tool and more detailed analysis. We also considering WP plugins which might be an AI tool to help developers with analyze and recommendations on how to fix performance issues.

See - #152 (comment)

Note

We also will be making documentation and continuous updates of documentation a key part of our long term goal to help HWP developers with performance of their HWP applications.

Adoption Strategy

We aim to create the best documentation for the WordPress Headless Community and give relevant documentation and help guides to cover some of the difficult parts around performance of HWP applications.

We also aim to release a an initial POC profiling tool with basic capabilities around requests and caching. We also aim ot release a POC package for correlating frontend and backend requests for your Next.js application with a longer term view of this being framework agnostic. We also aim to update this RFC with next steps for "Logging" once we complete the initial phase of work.

We will promote and encourage community contributions and reviews to foster a collaborative learning environment.

How Do We Teach This?

We will ensure that our documentation and tools are easy to follow and use with good documentation. We will also provide strong community support and listen to feedback from our community it trying to help deliver a better experience for a HWP developer for dealing with performance.

How Can You Help?

We are excited about this new toolkit and the opportunities it presents for the WordPress headless community.

We’d love your feedback on the following:

• Is this the best approach for the community regarding performance and logging? Are there better approaches we should consider?
• Are we missing any major topics or examples?
• Would you like to contribute? See our contributing guide https://github.com/wpengine/hwptoolkit/blob/main/CONTRIBUTING.md
• What other topics would you like us to cover? We would love to hear from you!

RFC Changelog

• May 2, 2025 - Initial RFC for "Performance and Logging" and identifying first steps of a long term iteration process for performance and logging.
• July 21,2025 - Add RFC for logging - RFC: Performance and Logging in Headless WordPress Applications #152 (comment)

[colinmurphy]

Just to note we are now actively working on this in Q3 (see sprint board - - Headless OSS (view))

1. WPGraphQL Logging (Logging wp-graphql/wp-graphql#3292) - Add comprehensive logging functionality to WPGraphQL for debugging, performance monitoring, and security tracking.

2. Performance Data in Headless WordPress Applications(RFC: Performance and Logging in Headless WordPress Applications #152) - Help developers identify key performance issues by supplying relevant documentation (such as best practices, debug help guides) and tools to analyze the performance of their headless application.

We have two tickets for defining both logging and also performance:

Logging: #162
Performance: #327

[colinmurphy]

WPGraphQL Logging Plugin

Overview

For logging, we plan to deliver an MVP WordPress logging plugin for WPGraphQL with an event-based subscriber system.

Key Features

• Request Lifecycle - We aim to develop an event-based system for WPGraphQL request lifecycle and capture key logging points and metrics in the lifecycle and log these before WPGraphQL sends the response back to the client.
• Extendability - We will ensure that developers or WPGraphQL plugins can hook into the lifecycle and capture or add data to the lifecycle.
• Flexibility - We are going to use Monolog an established open-source PHP library for logging data which also allows flexibility for developers.

Note

For MVP, we will be only logging to either a database table or file but as this is Monolog, a user could log to different or multiple sources if they wished.

Motivation

Our motivation is to help the community when debugging their headless WordPress and help identify quickly key performance bottlenecks in their headless application.

Outcomes

• Deliver a logging plugin for WPGraphQL with some admin functionality
• Develop a concept of a request lifecycle and identify key logging points and metrics which could help users debug their headless applications faster and improve their experience of headless WordPress
• Help support our community with a better understanding and experience when debugging performance issues and identify these issues quicker

Timeline

Q3 as part of our goals for this quarter:

WPGraphQL Logging (wp-graphql/wp-graphql#3292) - Add comprehensive logging functionality to WPGraphQL for debugging, performance monitoring, and security tracking.

Future Considerations

A few ideas we have for future iterations:

• Query AI Analysis - Analyze key areas of the request and give users feedback either by subscribing to key events or even maybe an action within the WordPress admin.
• Monolog Advanced Functionality - We can look at other options around logging and having more advanced configuration to send data to multiple destinations depending on the level logged.
• Webhooks Extendability - Add a concept of webhooks to subscribe to events and push log and metric data to different sources.
• Advanced Admin Functionality - Consider some features such as filters/sort, export, re-run queries and also more advanced analysis.

[theodesp]

Spike: Performance and Metrics in Headless WordPress Applications

Overview

This spike aims to define the documentation and tooling necessary to assist developers in identifying and resolving key performance issues within their headless WordPress applications. Building upon the initial RFC and recent HackDay efforts, we will validate the "why" behind these initiatives and establish clear, measurable outcomes for Q3.

• Initial RFC: RFC: Performance and Logging in Headless WordPress Applications #152
• Hackday Branch: https://github.com/wpengine/hwptoolkit/tree/hackday-wpgql-logger-experiment

---

We have identified two primary options for performance tooling:

---

Option One: Enhance QueryAnalyzer with Heuristic Rules

This option focuses on extending the existing QueryAnalyzer extension of wp-graphql to incorporate heuristic rules. These rules will analyze query complexity patterns and highlight potential performance bottlenecks.

General Description

The QueryAnalyzer will be enhanced to automatically detect and flag GraphQL query patterns that are likely to lead to performance degradation. This will provide developers with immediate feedback on their query structures, guiding them towards more efficient implementations.

Pros

• Proactive identification of performance issues during development
• Guides developers toward best practices without manual intervention
• Integrates directly with wp-graphql for a seamless experience

Cons

• May require ongoing maintenance to keep rules relevant with new GraphQL features
• False positives could potentially occur with complex, but optimized, queries
• Initial development effort to define and implement robust heuristic rules

Outcomes

• Rule 1: Nested Queries – Detect and flag deeply nested GraphQL queries (e.g., >3 levels) that could lead to N+1 problems.
• Rule 2: Excessive Field Selection – Identify queries selecting an unusually large number of fields from a single type, suggesting over-fetching.
• Rule 3: Unfiltered Lists – Warn about queries requesting large lists without filtering or pagination.
• Rule 4: Complexity Score – Calculate a complexity score based on nesting, fields, and relationships; flag queries that exceed a threshold.

Implementation Outcomes

• Plugin Development: Develop a plugin named WPGraphQL Query Optimizer.
• Heuristic Rule Engine: Implement logic for processing defined heuristic rules.
• Developer Feedback Mechanism: Integrate feedback in GraphQL responses (e.g., warnings).
• Configuration Options: Provide dashboard settings to configure thresholds and enable/disable rules.
• Documentation: Create detailed documentation on installation, configuration, and usage.

Estimated Effort: 2–3 sprints

---

Option Two: Tracing with Additional Metrics and Debug Toolbar

This option involves augmenting the QueryLog and TracingLog of wp-graphql to capture more detailed metrics such as memory usage. This data will be consumed by a debug toolbar or IDE for field- and query-level performance insights.

General Description

The wp-graphql extension’s logging will be expanded to include performance metrics like memory consumption, execution times, and SQL performance. This data will be surfaced in a debug interface to help developers pinpoint issues.

Pros

• Provides highly granular performance insights
• Enables deep-dive analysis at the field and SQL query level
• Supports identification of memory leaks and inefficient data retrieval

Cons

• Requires a robust debug toolbar or IDE integration
• May introduce slight overhead (development-only feature, behind a flag)
• Development of the debug interface is an additional effort

Outcomes

• Outcome 1: Enhanced Tracing: Include memory usage, CPU time, and query count for each GraphQL field and SQL query.
• Outcome 2: Debug Toolbar/IDE Integration: Build a toolbar or IDE plugin to visualize enhanced logs.

Implementation Outcomes

• WordPress Plugin for Enhanced Tracing: Develop a plugin named WPGraphQL Tracing Enhancements to augment QueryLog and TracingLog.
• Debug Toolbar (JS/React): Build a JavaScript/React-based toolbar that loads with the headless app, consumes the trace data, and visualizes it for developers.

Estimated Effort: 3–5 sprints