Flag of Ukraine
SymfonyCasts stands united with the people of Ukraine

Installing the Agent, Probe & Chrome Extension

Video not working?

It looks like your browser may not support the H264 codec. If you're using Linux, try a different browser or try installing the gstreamer0.10-ffmpeg gstreamer0.10-plugins-good packages.

Thanks! This saves us from needing to use Flash or encode videos in multiple formats. And that let's us get back to making more videos :). But as always, please feel free to message us.

So... let's get these pieces installed! Back on the install page, the setup details will vary based on your operating system. Fortunately, Blackfire has details for pretty much all situations. I'm on a Mac and will use Homebrew to get everything working.

I'll copy the brew tap command, move to my terminal, open a new tab and paste:

brew tap blackfireio/homebrew-blackfire

Installing the Agent

That gives me access to the Blackfire packages. Now, install the agent - that's the "daemon" that runs in the background - with:

brew install blackfire-agent

Perfect! It says I need to "register" my agent. And... the browser instructions confirm that! I'll copy that command, clear the screen and paste:

sudo blackfire-agent --register

This is going to ask us for our "Server Id" and "Server Token". These are... basically an internal "username and password" that the agent will use to tell the Blackfire servers which account the profiles should be attached to. Copy the Server Id, paste, copy the Server Token, paste and... we're good!

Finally, remember how the "agent" is a service that runs in the background? We just installed the agent, but it's not running yet. Back in the docs, the next two commands set up the agent as a "service" in Brew, so that it will always be running. Copy the first, paste.

ln -sfv /usr/local/opt/blackfire-agent/*.plist ~/Library/LaunchAgents/

Then spin back over again, copy the launchctl load command... and paste that.

launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.blackfire-agent.plist

Cool! If everything worked, the Blackfire agent is now running in the background. You wont really ever see it or care that it's there... but it is... waiting for data.

Installing the Probe

Back on the install docs, the next piece we need is the PHP extension - the probe. Skip this CLI tool for now - we won't need it until later.

To install the PHP extension, we'll once again use brew. But... hopefully you're not still using PHP 5.6. Let me head over to my terminal and see what version I'm running:

php --version

7.3.6. Brilliant! So I'll run:

brew install blackfire-php73

Notice that the extension doesn't need any authentication info - like a server Id or token. It's beautifully dumb: its job is to profile data, send it to the agent, and let it worry about authentication with the Blackfire servers.

We do, however, as it says, need to restart our web server. For us, that means going to the other terminal tab, hitting Control + C, and then running

symfony serve

Is the Blackfire extension working? I don't know! Because we're using Symfony, an easy way to check is to hover over the web debug toolbar and click the "View phpinfo()" link. Let's see... yep! The Blackfire PHP extension is here.


If you have XDebug installed, disable it for the best results.

Installing the Browser Extension

At this point, our server is set up and ready to profile! Victory! The only thing we need now is a way to tell the probe when to activate. That's the job of the browser extension.

Go almost all the way back to the top of the install page where they talk about the different pieces. I'm using Chrome, so I'll click the Google Chrome extension link. I don't have it installed yet, so let's fix that: Add to Chrome.

There it is! If you refresh the docs... yep! It sees the extension.

Profiling our First Page

Hey! We're ready to profile! Ahhhh! Where should we start? Let's... just click to view details about any Big Foot sighting. All of this data comes from some data fixtures that we used to pre-populate the database while setting up the project. It uses a bunch of random data up here... and each sighting has a bunch of random comments.

When we loaded this page a second ago, the PHP extension - the probe - did nothing. To activate it, click the browser extension.

Moment of truth! When we click profile, the plugin will send a request to this page with a special header that tells the probe to activate and start profiling. Click "Profile"!

There it goes! It goes from 0 to 100% as it actually makes 10 requests and averages their data. We can also give this "profile" a name to keep our account organized: I'll say [Recording] Show page initial and hit enter.

Troubleshooting Failure

If you got to 100%, congrats! If you got an error... wah wah. This is the most common place for something to go wrong... and the error will almost always be the same: Probe not found. This might mean that you forgot to install the PHP extension, or that the PHP extension was installed on a different PHP binary... or that the agent isn't running... or that the agent is running but you misconfigured the server id and token. They have great docs to help with this.

But we had success! Click the "View Call Graph" button to go to a URL on their site. Hello beautiful Blackfire profile. Wow.

Next, let's start diving into this mountain of information and see how we can use it to find hidden sasquatch... I mean, hidden performance bugs.

Leave a comment!

Login or Register to join the conversation
Default user avatar
Default user avatar Artem Khodos | posted 3 years ago | edited

One thing is currently missed into README.md of the sample project is database. If you have no MySQL installed on the host machine, you can use docker-compose.
My simple docker-compose.yaml looks like:
version: '3'


image: mysql:5.7
  MYSQL_DATABASE: blackfire
  - 3306:3306


1 Reply

Thanks for sharing with others. Cheers!

Dang Avatar

Hi, When I click on Profile! on the Chrome extension, I only get 10% and then stop. I never have 100% done.
I have blackfire-agent run and probe extension enable (by check php -m).
Am I missing something on installation in 2022?


Hey Dang,

Do you get any errors? I'd expect an authorization error or something similar

Dang Avatar

Yes, when I run by the CLI: blackfire curl I have this error: Are you authorized to profile this page? No probe response, Blackfire not properly installed or invalid signature for relaying agent.

I installed with the Blackfire v2 , option "as quickly as possible" on linux machine. I have then the file .blackfire.ini with client-id, client-token and a file named agent in /etc/blackfire which contains the server-id and server-token.


Hey Dang,

I found this warning in the Blackfire page

PHP will likely crash when Blackfire is used when one of the following extensions is also enabled: XHProf, Pinba, and Suhosin.

If XDebug is installed, the PHP engine may not behave as expected; consider disabling it when profiling.

If pcov extension is installed, Blackfire will not behave as expected; consider disabling it when profiling.

Is it possible that you have any of those tools installed? If that's not the case, I think you'll have to configure the "probe" to log more info and see if we find a hint of the problem https://blackfire.io/docs/php/configuration
Oh, and this may sound silly, but double-check that you introduced your credentials correctly

hanen Avatar

I cant install the probe library in windows .. PHP Startup: Unable to load dynamic library 'blackfire.so' (tried: C:\xampp\php\ext\blackfire.so (Le module sp´┐¢cifi´┐¢ est introuvable.), C:\xampp\php\ext\php_blackfire.so.dll


Hey hanen

Interesting, have you followed this installation steps? https://blackfire.io/docs/u...
I guess you have wrong DLL file


hanen Avatar

hi , I tried loding the following file and it works :)))


Perfect! Looks like you had wrong library, I'm glad to see that everything is solved!


Cat in space

"Houston: no signs of life"
Start the conversation!

This tutorial can be used to learn how to profile any app - including Symfony 5.

What PHP libraries does this tutorial use?

// composer.json
    "require": {
        "php": "^7.1.3",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "blackfire/php-sdk": "^1.20", // v1.20.0
        "composer/package-versions-deprecated": "^1.11", // 1.11.99
        "doctrine/annotations": "^1.0", // v1.8.0
        "doctrine/doctrine-bundle": "^1.6.10|^2.0", // 1.11.2
        "doctrine/doctrine-migrations-bundle": "^1.3|^2.0", // v2.0.0
        "doctrine/orm": "^2.5.11", // v2.6.4
        "phpdocumentor/reflection-docblock": "^3.0|^4.0", // 4.3.2
        "sensio/framework-extra-bundle": "^5.4", // v5.5.1
        "symfony/console": "4.3.*", // v4.3.10
        "symfony/dotenv": "4.3.*", // v4.3.10
        "symfony/flex": "^1.9", // v1.18.7
        "symfony/form": "4.3.*", // v4.3.10
        "symfony/framework-bundle": "4.3.*", // v4.3.9
        "symfony/http-client": "4.3.*", // v4.3.10
        "symfony/property-access": "4.3.*", // v4.3.10
        "symfony/property-info": "4.3.*", // v4.3.10
        "symfony/security-bundle": "4.3.*", // v4.3.10
        "symfony/serializer": "4.3.*", // v4.3.10
        "symfony/twig-bundle": "4.3.*", // v4.3.10
        "symfony/validator": "4.3.*", // v4.3.10
        "symfony/webpack-encore-bundle": "^1.6", // v1.7.2
        "symfony/yaml": "4.3.*", // v4.3.10
        "twig/extensions": "^1.5" // v1.5.4
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.2", // 3.2.2
        "easycorp/easy-log-handler": "^1.0.7", // v1.0.9
        "fzaninotto/faker": "^1.8", // v1.8.0
        "symfony/browser-kit": "4.3.*", // v4.3.10
        "symfony/css-selector": "4.3.*", // v4.3.10
        "symfony/debug-bundle": "4.3.*", // v4.3.10
        "symfony/maker-bundle": "^1.13", // v1.14.3
        "symfony/monolog-bundle": "^3.0", // v3.5.0
        "symfony/phpunit-bridge": "^5.0", // v5.0.3
        "symfony/stopwatch": "4.3.*", // v4.3.10
        "symfony/var-dumper": "4.3.*", // v4.3.10
        "symfony/web-profiler-bundle": "4.3.*" // v4.3.10