Xdebug is a PHP extension for debugging and performance profiling, and Webgrind is a browser-based tool for visually analyzing profiling data generated by Xdebug. Both tools come pre-installed in Seravo's local Docker development environment.
Note: Xdebug is intended strictly for local development environments, as it significantly slows down PHP execution. To profile performance in production or staging environments, use the Tideways profiling tool.
Step 1: Enable Xdebug in the Development Container
By default, Xdebug is disabled in the local Docker environment to keep your site running at full speed. Enable Xdebug inside the development container (seravo-docker ssh):
wp-xdebug-on
Once you have finished profiling, disable Xdebug again with:
wp-xdebug-off
Step 2: Profile a Page and Inspect Results in Webgrind
With Xdebug enabled, you can profile any page load on your local site by appending ?XDEBUG_PROFILE to the URL (or &XDEBUG_PROFILE if the URL already contains query parameters).
Example: Profiling the WordPress Admin Dashboard
Open the page you want to profile in your browser with the query parameter appended, for example:
http://wordpress.local/wp-admin/?XDEBUG_PROFILE
(The page load will take noticeably longer than usual because Xdebug records the execution time of every function call into a
cachegrind.out.*file.)Open Webgrind in your browser at
http://webgrind.<site>.local/(default:http://webgrind.wordpress.local/).Select the latest
cachegrindfile from the top dropdown menu (or leave it set to Auto (newest)) and click Update.
Webgrind interface displaying PHP function execution times, invocation counts, and relative costs after profiling.
Reading Webgrind Results
Webgrind lists all PHP functions executed during the page load. Pay particular attention to three columns:
Invocation Count: How many times the function was called during the page load. An unexpectedly high count often indicates an unnecessary loop or repeated database query.
Total Self Cost: How much time was spent executing the function's own code (excluding calls to other functions). This pinpoints direct bottlenecks.
Total Inclusive Cost: The total execution time of the function, including all child functions it called.
Tip: Profile dump files are stored in /tmp/ inside the container and can grow quite large. You can remove old profile dumps inside the container with rm -f /tmp/cachegrind.out.*.
Using the Xdebug Helper Browser Extension
If you prefer triggering profiling directly from your browser toolbar without manually typing ?XDEBUG_PROFILE into the address bar (for example, when profiling form submissions or AJAX requests), you can use the Xdebug Helper browser extension (available for Chrome and Firefox).
Configure the extension with the following settings:
IDE key:
vagrant(orPHPSTORM)Trace Trigger Value:
XDEBUG_TRACEProfile Trigger Value:
XDEBUG_PROFILE
Xdebug Helper browser extension settings showing the configured IDE key along with profile and trace trigger values.
Remote Step Debugging with Xdebug
In addition to profiling, Xdebug supports interactive step debugging, allowing you to set breakpoints in your code and inspect variable values during execution directly in your code editor (such as VS Code or PhpStorm).
Enable Xdebug inside the container (wp-xdebug-on) and configure your editor to listen for incoming Xdebug connections (default port 9003, or 9000 for Xdebug 2). Refer to your IDE's documentation for editor-specific setup instructions.
Common Issues and Troubleshooting
No profiling files appear in Webgrind's dropdown list: Verify that you enabled Xdebug inside the container with
wp-xdebug-onbefore loading the page with?XDEBUG_PROFILE.The local development site feels unusually slow: Xdebug was left enabled in the background. Disable it inside the container by running
wp-xdebug-off.http://webgrind.wordpress.local/fails to load: Ensure the local Docker environment is running (seravo-docker up) and that your project uses the defaultwordpress.localdomain (if you customized the domain inconfig.yml, usehttp://webgrind.<site>.local/).
See Also
Using Xdebug and Webgrind allows you to reliably pinpoint resource-heavy theme and plugin functions right in your local development environment. If you need assistance optimizing site performance or using development tools, our support team is happy to help at [email protected].


