# Blackfire

As the **official Upsun Fixed observability service**,
[Blackfire](https://www.blackfire.io/) helps you improve the performance of your apps at each stage of their lifecycle.
With Blackfire's unique Application Performance Monitoring (APM) and Profiling 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 Fixed and [works integrally with the Upsun Fixed workflow](https://www.youtube.com/watch?v=Bq-LFjgD6L0).
This results in an effortless setup process and smooth user experience.

**Note**: 

Blackfire.io can be bundled with Enterprise and Elite subscriptions as part of the Observability Suite.
To learn more, [contact Sales](https://upsun.com/contact-us/).
All customers can also subscribe to Blackfire separately.

## Set up Blackfire

### On a Grid infrastructure

If you're using a plan with the [Observability Suite](https://upsun.com/product/),
the [Blackfire automated integration](#automated-integration) is enabled on your environments by default.
Note that as an Observability Suite user, you can only access your Blackfire environments
after you've been granted access to the related Upsun Fixed project.
Therefore, to access your Blackfire environments, make sure you log in using your Upsun account.

If you have Grid environments without the Observability suite,
you need to enable the integration yourself.
To do so, follow these steps:

1. Create a [Blackfire account](https://blackfire.io/signup?target=/login), preferably using your Upsun Fixed login.
2. In your Blackfire account, create an organization.
   If you subscribed to Blackfire independently, your organization is automatically activated.
   If you subscribed to Blackfire through Upsun Fixed,
   [ask **Upsun Fixed** Support](https://console.upsun.com/-/users/~/tickets/open) to activate your organization.
3. In your organization, create an environment.
4. In your environment, click **Settings/Environment Credentials**.
5. Retrieve your Blackfire server ID and server token.
6. Follow [the instructions from the Blackfire documentation](https://blackfire.io/docs/integrations/paas/platformsh).

If you're using the [Managed Fastly CDN](https://fixed.docs.upsun.com/domains/cdn/managed-fastly.md),
it's already configured to operate with Blackfire.
If you're using a different [Content Delivery Network (CDN)](https://fixed.docs.upsun.com/domains/cdn.md),
make sure you [configure it](https://blackfire.io/docs/integrations/proxies/index)
to let Blackfire profile the code running on your servers.

### On Dedicated Gen 2 infrastructure

To install Blackfire on your Dedicated Gen 2 environments:

1. Create a [Blackfire account](https://blackfire.io/signup?target=/login), preferably using your Upsun Fixed login.
2. In your Blackfire account, create an organization.
   If you subscribed to Blackfire independently, your organization is automatically activated.
   If you subscribed to Blackfire through Upsun Fixed,
   [ask **Upsun Fixed** Support](https://console.upsun.com/-/users/~/tickets/open) to activate your organization.
3. In your organization, create an environment.
4. In your environment, click **Settings/Environment Credentials**.
5. Retrieve your Blackfire server ID and server token.
6. Send those credentials to [Support](https://console.upsun.com/-/users/~/tickets/open) so they complete the installation.

If you're using the [Managed Fastly CDN](https://fixed.docs.upsun.com/domains/cdn/managed-fastly.md),
it's already configured to operate with Blackfire.
If you're using a different [Content Delivery Network (CDN)](https://fixed.docs.upsun.com/domains/cdn.md),
make sure you [configure it](https://blackfire.io/docs/integrations/proxies/index)
to let Blackfire profile the code running on your servers.

### Automated integration

  **Observability Suite**

  This feature is available as part of the [Observability Suite](https://upsun.com/product/).
To add the Observability Suite to your project and take advantage of this feature,
[contact Sales](https://upsun.com/contact-us/).

The Blackfire automated integration is available for Grid.

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](https://www.blackfire.io/features/).
This includes monitoring, profiling, alerting, and build-related features.

When a Blackfire environment is created based on a Grid environment,
user access settings are replicated from the Upsun Fixed Console to Blackfire.

This includes all [access levels](https://blackfire.io/docs/up-and-running/access-management).

To access the 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 Fixed credentials.

You might have Blackfire variables already set on your project.
In this case, the existing variables override the settings of the automated integration.

Note that to trigger the synchronization of changes to users and their access levels,
you need to redeploy the environment.

## Get started with Blackfire Monitoring

Once Blackfire is [set up on your infrastructure](#set-up-blackfire),
to start monitoring your environment follow these steps:

### 1. Activate Blackfire Monitoring

If you want to monitor a PHP or Python app, Blackfire Monitoring is available by default on your environments.
You only need to [specify which environments](#2-enable-blackfire-monitoring-on-your-environments) you want to monitor.

You can override the default behavior and deactivate Blackfire Monitoring by setting a `env:BLACKFIRE_APM_ENABLED`
[environment variable](https://fixed.docs.upsun.com/development/variables/set-variables.md#create-environment-specific-variables) with a value of `0`.

To do so, create the following :

```bash
platform variable:create --level environment --prefix env: --name BLACKFIRE_APM_ENABLED --value 0
```

### 2. Enable Blackfire Monitoring on your environments

To enable Blackfire Monitoring on your environments, follow these steps:

1.  Go to your [organizations list](https://blackfire.io/my/organizations)
    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](https://fixed.docs.upsun.com/images/integrations/blackfire/blackfire-organization-monitoring.png "0.40")

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

    ![A screenshot of what's seen in Monitoring Activation](https://fixed.docs.upsun.com/images/integrations/blackfire/blackfire-monitoring-activation.png "0.40")

For more information on Blackfire monitoring features,
see the [Blackfire documentation](https://blackfire.io/docs/monitoring-cookbooks/index).

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

For more information on Blackfire profiling features,
see the [Blackfire documentation](https://blackfire.io/docs/profiling-cookbooks/index).

## Test the performance of each new deployment

Blackfire's native integration with Upsun Fixed 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](https://blackfire.io/docs/integrations/paas/platformsh#builds-level-production).

2.  Optional: set up an [integration with your Git provider](https://blackfire.io/docs/integrations/git/index)
    and get commit status updates from build reports.

3.  To test business-critical use cases, [write scenarios](https://blackfire.io/docs/builds-cookbooks/scenarios).

## Troubleshooting

### Bypass your reverse proxy, load balancer or CDN

To use [Blackfire profiling](#blackfire-profiling),
you need to bypass any reverse proxy, load balancer or [CDN](https://fixed.docs.upsun.com/domains/cdn.md) that sits in front of your app.
See [how to configure a bypass](https://blackfire.io/docs/reference-guide/reverse-proxies#documentation).

### 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](https://fixed.docs.upsun.com/define-routes/cache.md#allowing-only-specific-cookies) similar to the following:

```yaml  {location=".platform/routes.yaml"}
cache:
  enabled: true
  cookies: ["/SESS.*/", "__blackfire"]
```

## Get support

If you're experiencing issues with Blackfire and [troubleshooting](#troubleshooting) information doesn't help, follow these steps:

1. Retrieve [startup errors](#1-retrieve-startup-errors).
2. Retrieve your [Blackfire logs](#2-retrieve-your-blackfire-logs).
3. Send this data to [Blackfire Support](https://support.blackfire.io).

### 1. Retrieve startup errors

To retrieve startup errors, run the following command:

```bash
platform ssh -- php -d display_startup_errors=on --ri blackfire
```

### 2. Retrieve your Blackfire logs

To retrieve your Blackfire logs, follow these steps:

1.  On the environment where you're facing issues, create the following [variable](https://fixed.docs.upsun.com/development/variables/set-variables.md):

    ```bash
    platform 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:

    ```bash
    platform variable:create php:blackfire.log_level --value 4
    ```

3.  Start a profile or build.

4.  To display the logs, run the following command:

    ```bash
    platform ssh -- cat /tmp/blackfire.log > blackfire.log
    ```

After you've retrieved the logs, you can disable them.
To do so, run the following commands:

```bash
platform variable:delete php:blackfire.log_file
platform variable:delete php:blackfire.log_level
```