Blackfire for PHP and Python
Back to home
On this page
Full access to Blackfire is bundled with all your PHP and Python Upsun projects.
Blackfire is the official Upsun observability service that helps you improve the performance of your apps at each stage of their lifecycle. With Blackfire’s unique Application Performance Monitoring (APM), Profiling, Alerting, and Testing features, you can achieve the following goals:
-
Avoid performance bottlenecks by proactively identifying issues in your code
-
Promptly solve identified issues by taking advantage of actionable recommendations
-
Create performance budgets for critical parts of your app and get alerted of any problem before a change hits your production
Blackfire is installed natively on Upsun and works integrally with the Upsun workflow. This results in an effortless setup process and smooth user experience.
Get started with Blackfire
You can only access your Blackfire environments after you’ve been granted access to the related Upsun project. Therefore, to access your Blackfire environments, make sure you log in using your Upsun account.
To access a Blackfire environment, each project user needs a Blackfire account. When a project user doesn’t already have a Blackfire account, a new one is automatically created using the user’s Upsun credentials.
Note
If you’re using a Content Delivery Network (CDN), make sure you configure it to let Blackfire profile the code running on your servers.
Automated integration
The Blackfire automated integration is enabled on your environments by default.
When you create a new environment, it automatically triggers the creation of a Blackfire environment with the same settings. On this Blackfire environment, you have access to all the features provided by Blackfire. This includes monitoring, profiling, alerting, and build-related features.
Note that Blackfire monitoring is enabled by default on your production environment. On other environment types, you need to enable it. User access settings are replicated from the Upsun Console to Blackfire – this includes all access levels.
You might have Blackfire variables already set on your project. In this case, the existing variables override the settings of the automated integration.
Note
To trigger the synchronization of changes to users and their access levels, you need to redeploy the environment.
Blackfire monitoring
Blackfire monitoring is enabled by default on your production environment. To enable Blackfire monitoring on your development or staging environments, follow these steps:
-
Go to your organizations list and select the organization where you want to enable Blackfire monitoring.
-
Click Organization Monitoring Usage.
-
In the Monitoring Activation section, enable monitoring on the environments of your choice.
For more information on Blackfire monitoring features, see the Blackfire documentation.
Blackfire Profiling
While your code is running, the Blackfire profiler collects deep performance metrics and provides full details and context of your code’s behavior. This helps you find the root cause of performance bottlenecks.
Blackfire lets you profile your application anywhere it’s deployed, including on your local development machines. Using a browser extension or CLI command, you can profile HTTP requests, CLI scripts, Consumers, and Daemons.
While HTTP requests can be profiled out-of-the-box, CLI profiling requires a specific configuration.
For more information on Blackfire profiling features, see the Blackfire documentation.
Test the performance of each new deployment
Blackfire’s native integration with Upsun enables you to test your app’s performance every time you deploy a branch in production, staging, or development. Follow these steps:
-
Set up the Blackfire Builds integration.
-
Optional: set up an integration with your Git provider and get commit status updates from build reports.
-
Recommended: test business-critical use cases, with Blackfire synthetic monitoring.
Troubleshooting
Bypass your reverse proxy, load balancer or CDN
To use Blackfire profiling, you need to bypass any reverse proxy, load balancer or CDN that sits in front of your app.
See how to configure a bypass.
Configure your HTTP cache
To take advantage of Blackfire features while using the HTTP cache with cookies,
allow the __blackfire
cookie to go through the cache.
To do so, add a configuration similar to the following:
cache:
enabled: true
cookies: ["/SESS.*/", "__blackfire"]
Get support
If you’re experiencing issues with Blackfire and troubleshooting information doesn’t help, follow these steps:
- Retrieve startup errors.
- Retrieve your Blackfire logs.
- Send this data to Blackfire Support.
1. Retrieve startup errors
To retrieve startup errors, run the following command:
upsun ssh -- php -d display_startup_errors=on --ri blackfire
2. Retrieve your Blackfire logs
To retrieve your Blackfire logs, follow these steps:
-
On the environment where you’re facing issues, create the following variable:
upsun variable:create php:blackfire.log_file --value /tmp/blackfire.log
-
To set the verbosity of the logs to level 4 (debug level), create the following variable:
upsun variable:create php:blackfire.log_level --value 4
-
Start a profile or build.
-
To display the logs, run the following command:
upsun ssh -- cat /tmp/blackfire.log > blackfire.log
After you’ve retrieved the logs, you can disable them. To do so, run the following commands:
upsun variable:delete php:blackfire.log_file
upsun variable:delete php:blackfire.log_level