Profiling PHP websites with Xdebug

Xdebug is a PHP extension which you can use to profile websites. If something is running slowly, Xdebug can help identify exactly what is going on. It’s included in every Webslice Container.

When Xdebug is enabled, it creates cachegrind files every time a web page is loaded. These files contain a code breakdown of the PHP application, showing how much time is spent running each function. Finding slow code is a crucial step in the optimization process, so these files can be very valuable.

This guide will cover how to enable Xdebug and set up a basic UI tool for analysing data called Webgrind. Xdebug’s official documentation includes a lot of other topics that aren’t covered here.

Setting up Xdebug

Caution

Because Xdebug is resource-intensive, it will slow applications down as it runs. If you are profiling a live site, you’ll need to be careful about when you run it. Aim for a quiet period, when traffic is as low as possible, to avoid worsening site performance for visitors.

You can enable Xdebug from the PHP configuration directory of the Webslice Container. Start by opening that directory:

cd /container/config/php/conf.d

You will see all PHP extensions that are currently enabled. Xdebug is disabled by default, so don’t expect to see it in this list. (This stops it from using a lot of resources unnecessarily.)

Enable Xdebug:

ln -s ../mods-available/xdebug.ini xdebug.ini

Next, edit the extension’s configuration file to ensure that it will run:

vim ../mods-available/xdebug.ini

Remove the semicolons (;) to uncomment the last two lines:

; xdebug.mode=profile
; xdebug.output_dir=/container/application/

By default, the output directory is set to /container/application. If you change this, note the new location. You’ll need it to set up Webgrind.

Restart the container for your configuration file changes to take effect. Now, every time the site receives a visitor, Xdebug will generate cachegrind files which will be saved in the output directory.

Setting up Webgrind

Webgrind is an Xdebug profiling web frontend. It provides a dashboard that displays the cachegrind files created by Xdebug. This is easy to set up within a container. For the purpose of this demo, the dashboard page will be accessible via example.com/webgrind.

Navigate to the container’s public directory and clone the webgrind repository:

cd /container/application/public
git clone https://github.com/jokkedk/webgrind.git

By default, webgrind will look for cachegrind files in /tmp. To change this path, open the config.php file:

vim webgrind/config.php

and modify the static $profileDir variable:

static $profileDir = '/container/application';

Next, navigate to the webgrind dashboard using the URL example.com/webgrind, and you’ll see your dashboard.

Using the Webgrind dashboard

Use the drop-down menu to select which cachegrind files to view. You’ll see a time-based summary of each function call in the application.

You can choose to see times either as a percentage, or as raw milliseconds. You might find percentages easier to analyze. For example any function that takes up 50% of the time, regardless of the number of milliseconds, is probably worth investigating.

Disable Xdebug when you are finished

As long as Xdebug is running, your site will probably slow down under the load. To disable Xdebug, unlink the extension in /container/config/php/conf.d and then restart the container. Remember to also remove the Webgrind repository when you are finished with it.