Skip to main content

Performance Profiling: Xdebug & Webgrind

Learn how to identify slow PHP functions on your WordPress site in Seravo's local development environment using Xdebug and Webgrind. See instructions for enabling profiling and analyzing results.

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

  1. 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.)

  2. Open Webgrind in your browser at http://webgrind.<site>.local/ (default: http://webgrind.wordpress.local/).

  3. Select the latest cachegrind file from the top dropdown menu (or leave it set to Auto (newest)) and click Update.

Xdebug in Vagrant

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 (or PHPSTORM)

  • Trace Trigger Value: XDEBUG_TRACE

  • Profile Trigger Value: XDEBUG_PROFILE

xdebug helper chrome extension

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-on before 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 default wordpress.local domain (if you customized the domain in config.yml, use http://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].

Did this answer your question?