Frequent solutions and debugging walkthrough
This is the most common issue when installing the Blackfire stack.
Following Blackfire security principles, the probe does not expose anything if you are not allowed to profile, misconfigured it, or even forgot to install it. Therefore this issue can not be diagnosed automatically.
ℹ️ : Adobe Commerce Cloud and Platform.sh users benefit from a special configuration. If you use one of those platforms, please follow the dedicated troubleshooting documentation on their documentation sites:
If this issue occurs, please follow these steps:
1. Make sure the Agent is running
A common situation is where the Blackfire Agent is no longer running. In this situation, the Blackfire Probe will not be able to profile the request. Double-check to make sure that the Blackfire Agent is still running.
You may restart the agent with the following command:
sudo systemctl restart blackfire-agent.service
# Agent v1
brew services restart blackfire-agent
# Agent v2
brew services restart blackfire
2. Make sure the Blackfire probe is properly installed/enabled.
Use the following command to check if Blackfire probe is installed
Then check if Blackfire is listed in the resulted text.
ℹ️ : You may use a simple
phpinfo() script in a web context and look for Blackfire configuration.
Use the following command to check if the Python Probe is installed correctly:
pip show blackfire
The should output the following (version may vary):
Summary: Blackfire Python SDK
3. Check configuration
Ensure that you properly configured your Blackfire server credentials via
blackfire-agent -register . You can display the current configuration with
4. Restart your web-server or your FPM
And check that there are no error messages.
5. Make sure the page you try to profile is served by your application runtime
Do you have any proxy, cache or load balancer configured? Make sure they let Blackfire reach the server.
For example profiling a web server directory listing won't work. The same applies to single-page web-app as files will probably be served directly by the web-server. In this last case, you probably want to profile XHR requests instead.
6. Check versions
Ensure you're using the latest Agent, Probe, and Client (Browser extension or CLI tool). This is quite easy as this page will tell you if they're outdated.
7. Check logs
Collect logs and look for any error messages in the logs.
8. Check if SELinux is enabled
If you are using a flavor of Linux that uses Security-Enhanced Linux (SELinux), see our dedicated information on getting Blackfire to work in SELinux environments.
8. Contact our support
⚠️ : Don't forget to add both the Probe and the Agent logs. Please understand that our support team will need at least level 4 logs to help you. Read how to collect them here.
⚠️ : If your application is hosted on some of our Hosting Partners, you may not be able to collect agent logs. Please make sure to specify this in your support request.