Tag Archives: debug

Manual install and configuration of blackfire.io for Mac Ports in Mac OS X

blackfire.io is an awesome profiler for PHP done by SensioLabs, the company behind Symfony2. It automatically instruments your code to gather data about consumed server resources like memory, CPU time, and I/O. It’s very useful to find bottlenecks in your code.

blackfire.io is made of five main components:

  • The Agent is a server-side daemon that aggregates and forwards profiles to blackfire.io
  • The Probe is a PHP extension that gathers the raw performance profiles
  • The Client is a CLI tool used to trigger profiling
  • The Companion is a web browser extension used to trigger profiling
  • The Website is used to visualize the profiles


To use it in Mac OS X with Mac Ports you have to do a manual installation. Here is the different components installation process.


Download and install it’s files:

$ curl -O http://packages.blackfire.io/binaries/blackfire-agent/1.5.1/blackfire-agent-darwin_amd64.tar.gz
$ tar xzvf blackfire-agent-darwin_amd64.tar.gz
$ sudo mv etc/blackfire /opt/local/etc/
$ sudo chown -R root:admin /opt/local/etc/blackfire
$ sudo mv usr/share/man/man1/blackfire-agent.1.gz /opt/local/share/man/man1/
$ sudo chown root:admin /opt/local/share/man/man1/blackfire-agent.1.gz
$ sudo mv usr/bin/blackfire* /opt/local/bin/
$ sudo chown root:admin /opt/local/bin/blackfire*
$ sudo mkdir -p /opt/local/var/log/blackfire
$ sudo ln -s /opt/local/etc/blackfire /usr/local/etc/blackfire

Create an agent configuration file in /opt/local/etc/blackfire/agent changing the log/socket files to the paths inside Mac Ports installation (/opt/local) and with your server id and token from https://blackfire.io/account/credentials#server:


Now you can run it with this command:

$ sudo blackfire-agent

But it’s better to register a service using launchctl. Create a file called /opt/local/etc/LaunchDaemons/com.sensiolabs.blackfire-agent/com.sensiolabs.blackfire-agent.plist with this content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Make sure this file is owned by root and create an executable link to it in /Library/LaunchDaemons/com.sensiolabs.blackfire-agent.plist:

$ sudo chown root:admin /opt/local/etc/LaunchDaemons/com.sensiolabs.blackfire-agent/com.sensiolabs.blackfire-agent.plist
$ sudo ln -s /opt/local/etc/LaunchDaemons/com.sensiolabs.blackfire-agent/com.sensiolabs.blackfire-agent.plist /Library/LaunchDaemons/com.sensiolabs.blackfire-agent.plist
$ sudo chmod 755 /Library/LaunchDaemons/com.sensiolabs.blackfire-agent.plist

Load the service configuration file:

$ sudo launchctl load /Library/LaunchDaemons/com.sensiolabs.blackfire-agent.plist

And from now on you’ll be able to start and stop it as any other service:

$ sudo launchctl start com.sensiolabs.blackfire-agent
$ sudo launchctl stop com.sensiolabs.blackfire-agent

You can check if it’s really running using :

$ sudo ps x | grep blackfire
  751   ??  Ss     0:00.09 /opt/local/bin/blackfire-agent


This is the extension used in the HTTP server. You need a different binary file depending on your PHP version. This script will download and configure it for you, you only need to change the server id and token:

$ PHP_VER=`php -v | head -n 1 | awk -F ' ' '{print $2}' | tr -d . | cut -c1-2`
$ EXT_DIR=`php -i | grep 'extension_dir' | awk -F ' => ' '{print $2}'`
$ sudo curl -o ${EXT_DIR}/blackfire.so http://packages.blackfire.io/binaries/blackfire-php/1.9.2/blackfire-php-darwin_amd64-php-${PHP_VER}.so
$ sudo chmod 755 ${EXT_DIR}/blackfire.so
$ PHP_INI=`php --ini | grep "Loaded Configuration File" | awk -F ' ' '{print $4}'`
$ echo "

blackfire.server_token=91bde3fa9350479ba84f90acab46b680142c0f6fe8154a649e82d0d2ddadfa93" | sudo tee -a $PHP_INI

Restart your HTTP server (Apache in my case) and also test with this command if the extension is correctly loaded by PHP:

$ php -m | grep blackfire


The client binary file is installed with the Agent in /opt/local/bin/blackfire but you can also download and install it separately:

$ curl http://packages.blackfire.io/binaries/blackfire-agent/1.5.1/blackfire-cli-darwin_amd64 > blackfire
$ sudo chown root:admin blackfire
$ sudo mv blackfire /opt/local/bin/blackfire

Now configure the client file with the credentials from https://blackfire.io/account/credentials#client:

$ blackfire config

This will create a file in your home folder called ~/.blackfire.ini. You’ll have to update its socket value so it’s the same as the one used in the Agent configuration file:



The companion is only available for Google Chrome at the moment from here: https://chrome.google.com/webstore/detail/blackfire-companion/miefikpgahefdbcgoiicnmpbeeomffld. Install it and you’ll see a new icon in your browser that displays the different profiler slots.

Once everything is installed, configured and running just go to the URL in your server you want to profile and click “Profile!” in the Companion.


Ref: https://blackfire.io/getting-started