PHP profiling with XHprof

brianmercer's picture

If you're looking to track down the module which is killing your page load times, you may need profiling. Most people have used xdebug for this in the past with something like webgrind to display the information. Things have gotten easier.

Facebook has developed a PHP extension called XHprof and released it under the Apache license. It comes with a nice sample web interface.

While this article formerly described the use of a module specifically for xhprof, the devs of the devel module have integrated XHprof into both the versions for Drupal 6.x and 7.x and there's no longer any need to use a separate module.

The XHprof extension is available through PECL, but I made an Ubuntu package for ease of installation. So for those Ubuntu users, add my repo with

aptitude install python-software-properties
add-apt-repository ppa:brianmercer/php5-xhprof
aptitude update
aptitude install php5-xhprof graphviz

The graphviz package is required to generate the "callgraphs". Restart your php-fpm or apache or whatever you use for php.

Enable the devel module and enter the following values:

XHprof directory:  /usr/share/php5-xhprof/

XHProf URL: /xhprof_html

and for nginx place the following locations at the top of your server config:
location ^~ /xhprof_html/ {
    root /usr/share/php5-xhprof/;
    include /etc/nginx/fastcgi_params;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME /usr/share/php5-xhprof$fastcgi_script_name;
    fastcgi_pass php;

    location ~ ^.*\.(css|js|gif)$ {}

By default, XHprof is configured to place the dump files in /tmp. Feel free to delete them after you're done. To disable XHprof you can remove the package through apt or just comment out the lines in /etc/php5/conf.d/xhprof.ini with semicolons and restart php.


If you're using Drupal 7...

brianmercer's picture

EDIT: Now using the same configuration with D6 and D7 with devel module.

Thanks Brian, it sounds very

omega8cc's picture

Thanks Brian, it sounds very interesting. Definitely something to be added as a must have to my performance toolbox.

Thanks for sharing this!

ximo's picture

Tried your Nginx configuration, but it would only give me 404s. Not sure why, maybe it clashed with the rest of my server configuration. Anyway, I rewrote it into a separate server definition for XHProf, and lo and behold, it worked!

upstream php {
    server; # Or wherever your PHP-FPM service runs

server {
    server_name  xhprof;

    root   /usr/share/php5-xhprof/xhprof_html;
    index  index.php;

    location ~ .php$ {
        include        fastcgi.conf;
        fastcgi_index  index.php;
        fastcgi_pass   php;

That makes the URL for viewing XHProf reports http://xhprof (you obviously need an entry for this in /etc/hosts), which you need to specify in Devel's settings without a trailing slash.


I also had problems installing XHProf using Pecl in the first place, as its directory structure is incompatible with how Pecl does things. As I had already started with Pecl and didn't want to mess things up by trying Brian's (probably great) Ubuntu package (I'm on Debian Lenny), I followed the instructions by skwirblies on this bug report and completed the Pecl installation.

That left me without the /usr/share/php5-xhprof directory though, so I simply downloaded it from and unpacked it to /usr/share/php5-xhprof. Not sure this is as debianized as Brian's solution, but it works for me.

Hope this can help someone out there.


candelas's picture

big help

Update for maverick?

rfay's picture

Could you update the PPA for Maverick? (And Natty shortly?)

I get

maybe a connection problem?

candelas's picture

the other day i had that error when i tried to install but 15min later i could.

Doesn't work on my nginx server。

kurtzhong's picture

I am running drupal 7 on my Ubuntu Natty with Nginx, and you really help me a lot. Thanks a lot for your work.

The only problem is that after I add the Nginx configuration to my sites conf file, I couldn't restart my nginx server and it give me some error like .

Restarting nginx: nginx: [emerg] no port in upstream "php" in /etc/nginx/sites-enabled/
nginx: configuration file /etc/nginx/nginx.conf test failed

Any clue about this?

In place offastcgi_pass

brianmercer's picture

In place of

fastcgi_pass php;

you should put whatever you use for fastcgi_pass. That might be

fastcgi_pass unix:/var/run/php5-fpm.sock;

You can also define an upstream in your nginx.conf that reads like this:
upstream anyname {
  server unix:/var/run/php5-fpm.sock;
  # or

and then use
  fastcgi_pass anyname;

which can make it easier to make global changes when you need to.

Thank you. I've changed my

kurtzhong's picture

Thank you. I've changed my conf to following, and it works for me.

location ~ ^/xhprof_html/ {
    root /usr/share/php5-xhprof/;
    include fastcgi_params;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME /usr/share/php5-xhprof/$fastcgi_script_name;

But I don't know why it works...

couldn't find add-apt-repository

cdoyle's picture

I didn't have add-apt-repository on my Ubuntu 10.04 box so I had to run the following to get it to work

sudo apt-get install --reinstall python-software-properties && sudo dpkg-reconfigure python-software-properties

Fyi, I added this to my apache2 config inside the virtualhost directive:

    Alias /xhprof_html /usr/share/php5-xhprof/xhprof_html/
    <Directory "/usr/share/php5-xhprof/xhprof_html/">
       Options FollowSymLinks
       AllowOverride All
       Order allow,deny
       Allow from all

cdoyle, this is the nginx

Fidelix's picture

cdoyle, this is the nginx group. The probability that your comment will be useful to someone is quite low.

Thanks for having the effort, though...

That's good info to have.

brianmercer's picture

That's good info to have. This page is number two on google rankings for "drupal xhprof" and not everyone has seen the advantages of nginx quite yet.

Brian, I tried this,but

yngens's picture


I tried this,but getting 'No XHProf runs specified in the URL.' notice.

xhprof in windows

Bhanuji's picture

hey please help me out ... here every settings u people told which can be worked in Ubuntu ....
I m using Windows,, with apache server..

can u please tell how to install this xhprof in D6 and D7.

Sorry, I have no experience

brianmercer's picture

Sorry, I have no experience setting up xhprof or any php extension on windows.

No windows support

Harry Slaughter's picture

There is no port of xhprof for windows.

You can still use xdebug though and get a lot of the same information.

Drupal tips, tricks and services - Effective Drupal

Does it work under Virtual hosts?

voipfc's picture

Does it work under Virtual hosts?

Does it have to be configured separately for each Virtual hosts configuration?

It depends on your setup, but

brianmercer's picture

It depends on your setup, but typically the xhprof config will appear inside each server{} definition.

What I do is put the xhprof location in another file and then put an "include /etc/nginx/includes/xhprof" in my server definition when I want it

Getting Fatal error: Class

ckng's picture


Fatal error: Class 'XHProfRuns_Default' not found in /var/www/d7/sites/all/modules/contrib/devel/devel.module on line 1023"

paths and nginx configuration seems correct, what might be the problem?

Found something similar reported here

CK Ng |

It's working for me with

brianmercer's picture

It's working for me with current versions.

  1. is xhprof installed? does this file exist: /usr/share/php5-xhprof/xhprof_lib/utils/xhprof_runs.php
  2. is xhprof activated? go to /admin/reports/status/php and look for the xhprof entry
  3. did you restart php after installing the xhprof package?

Yes to all 3. xhprof

ckng's picture

Yes to all 3.

xhprof 0.9.2
PHP 5.3.2 with php5-fpm

CK Ng |

Sorry, I can't reproduce

brianmercer's picture

Sorry, I can't reproduce this.

Check to make sure that /usr/share/php5-xhprof/xhprof_lib/utils/xhprof_runs.php and the folders are readable by all, or at least the user that runs your web daemon. Unless you're using some other advanced permissioning system.

Try a location of "/usr/share/php5-xhprof" without the trailing slash.

Disable xhprof and uninstall and then make sure the settings are gone using "drush @yoursite vget devel_" and delete the xhprof ones (or all) using "drush @yoursite vdel devel_" and then install and double check the path again.

Perhaps try the dev version of devel, although I just checked both and both work for me.

Almost out of ideas.

I'm following instruction

ckng's picture

I'm following instruction outlined here:
The /usr/share/php5-xhprof/xhprof_lib/utils/xhprof_runs.php is readable by all. Get it to load after chown them to same as nginx user (www-data), that's odd.

My page is having &amp; in the title, now the xhprof can't load the file
"Could not find file /tmp/4f0b313b205d0.Training ..."
where to file a bug report for xhprof?

I can temporarily change the title to solve it.
Thanks for the clue on file access, but it should be readable, tested with other readable files not owned by www-data they are working.

CK Ng |

Odd indeed. Maybe check the

brianmercer's picture

Odd indeed. Maybe check the xhprof files for selinux context with "ls -Z".

The new problem might have to do with spaces or international characters in the site name? Check out this patch.

I doubt there's any point in filing a bug against xhprof. It hasn't seen any development in years except a small patch to make it compatible with php 5.4.

selinux is not

ckng's picture

selinux is not installed.
Will do more tests and maybe reinstall when I got the time.


CK Ng |

I know this group is for

yngens's picture

I know this group is for Nginx-related issues, but I couldn't find similar discussion for Apache users. Could anyone share how to make xhprof_html publicl available on my Ubuntu 10.04 with Apache? After installation of the profile I have located several instances of it and not sure which path I should put for locate xhprof:

locate xhprof

I haven't tried this with

brianmercer's picture

I haven't tried this with Apache myself. I'd suggest using /usr/share/php in the devel module configuration, and the apache configuration at above, except with the locations edited to reflect your setup.

I've done that once and I

revagomes's picture

I've done that once and I created a sym link for /usr/share/php/xhprof_html on my drupal root path called xhprof.

After that you need to put your local URI plus "/xhprof_html" (i.e. http://localhost/mydrupalsite/xhprof) on devel's xhprof configuration form and its should be ready to use.

Keep in mind that we are whom will change the world! is powered by Drupal.

Brian and Renato, Thanks for

yngens's picture

Brian and Renato,

Thanks for suggestions. I am trying to get it work with the following settings:

  1. When I run 'locate xhprof' I get the following locations:

  1. On my devel setting page I have '/usr/share/php/' for 'xhprof directory' and '' for 'XHProf URL'.

  2. I have symlinked 'xhprof' to '/usr/share/php/xhprof_html' wtih

ln -s /usr/share/php/xhprof_html xhprof

  1. Finally when I go to I, unfortunately, get 'No XHProf runs specified in the URL.' message.

Sorry for hijacking Ngingx group to ask Apache related questions, however as Brian state above, this page is number two on google rankings for "drupal xhprof", there is no similar discussion for Apache users and unfortunately there is no Drupal6 backport of xhprof module to file a ticket:

Did I mention I am trying to setup xhprof profiling for a Drupal 6 website?

Did you created the symlink

revagomes's picture

Did you created the symlink on the root of your drupal installation?

I did that using D7 but 'm not sure if it makes much difference in this case.

Keep in mind that we are whom will change the world! is powered by Drupal.

Yes, in Drupal's root, so

yngens's picture

Yes, in Drupal's root, so that the url now looks like:

add /tmp to xhprof.ini

SocialNicheGuru's picture

I had to make sure that I added "xhprof.output_dir=/tmp"

==> /etc/php5/conf.d/xhprof.ini <==

I just wanted to try this out

kaido24's picture

I just wanted to try this out and used becouse I couldnt get this installed :) You can use this even with shared hosting! :) good luck!

Getting Reports for Drush but not Drupal calls

nooysters's picture

Check permissions on your output directory.
or whatever yours is.

Conf file

jmoughon's picture

I had to add a Conf file to /etc/apache2/conf.d:
Create/etc/apache2/conf.d/xhprof.conf with:
alias /xhprof_html "/usr/share/php5-xhprof/xhprof_html/"