Upsun User Documentation

Blackfire for PHP and Python

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!ยน A monthly $19 perk!
ยนTerms and conditions apply
Activate your 15-day trial

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 Anchor to this heading

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.

Automated integration Anchor to this heading

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.

Blackfire monitoring Anchor to this heading

Blackfire monitoring is enabled by default on your production environment. To enable Blackfire monitoring on your development or staging environments, follow these steps:

  1. Go to your organizations list and select the organization where you want to enable Blackfire monitoring.

  2. Click Organization Monitoring Usage.

    A screenshot of where to find Organization Monitoring Usage

  3. In the Monitoring Activation section, enable monitoring on the environments of your choice.

    A screenshot of what’s seen in Monitoring Activation

For more information on Blackfire monitoring features, see the Blackfire documentation.

Blackfire Profiling Anchor to this heading

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 Anchor to this heading

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:

  1. Set up the Blackfire Builds integration.

  2. Optional: set up an integration with your Git provider and get commit status updates from build reports.

  3. Recommended: test business-critical use cases, with Blackfire synthetic monitoring.

Troubleshooting Anchor to this heading

Bypass your reverse proxy, load balancer or CDN Anchor to this heading

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 Anchor to this heading

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:

.upsun/config.yaml
cache:
    enabled: true
    cookies: ["/SESS.*/", "__blackfire"]

Get support Anchor to this heading

If you’re experiencing issues with Blackfire and troubleshooting information doesn’t help, follow these steps:

  1. Retrieve startup errors.
  2. Retrieve your Blackfire logs.
  3. Send this data to Blackfire Support.

1. Retrieve startup errors Anchor to this heading

To retrieve startup errors, run the following command:

upsun ssh -- php -d display_startup_errors=on --ri blackfire

2. Retrieve your Blackfire logs Anchor to this heading

To retrieve your Blackfire logs, follow these steps:

  1. On the environment where you’re facing issues, create the following variable:

    upsun variable:create php:blackfire.log_file --value /tmp/blackfire.log
  2. 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
  3. Start a profile or build.

  4. 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

Is this page helpful?