1. Documentation
  2. Integrations
  3. Blackfire Player

Blackfire Player Requires Premium/Enterprise

Blackfire Player natively integrates Blackfire profiler. To use Blackfire Player with Blackfire profiler, add --blackfire-env option to your blackfire-player command. You may use either the environment name or its UUID:

1
blackfire-player run scenario.bkf --blackfire-env="Environment name"

Note

Instead of using the --blackfire-env CLI option, you may set the Blackfire environment in the scenario;

1
2
3
4
scenario
    name "Scenario Name"
    # Use the environment name (or UUID) you're targeting or false to disable
    blackfire "Environment name"

Note

To use Blackfire Player together with Blackfire Profiler, you need to correctly setup your client credentials, which are available at https://blackfire.io/my/settings/credentials

If you have installed the Blackfire CLI, ensure that you have run the command blackfire client:config at least once to create the ~/.blackfire.ini file where your credentials are be stored.

Alternatively, you can also set BLACKFIRE_CLIENT_ID and BLACKFIRE_CLIENT_TOKEN environment variables before running the Blackfire Player.

Builds

The Blackfire Player creates a build to group all the scenarios. Each scenario contains profiles and assertion reports for requests made in each step of the executed scenario.

Note

All requests are profiled by default. You can disable the profiler in a step or in a complete scenario by setting blackfire false.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
scenario
    name "Scenario with Blackfire"
    # Use the environment name (or UUID) you're targeting or false to disable
    blackfire true
    # ...

scenario
    name "Scenario without Blackfire"
    # You can disable Blackfire support on the scenario, or only on some steps
    blackfire false
    # ...

Assertions

All the assertions defined in .blackfire.yaml are automatically run alongside Blackfire Player expectations.

You also may add assertions within a step with assert instruction:

1
2
3
4
scenario
    visit url('/blog/')
        name "Blog homepage"
        assert main.peak_memory < 10M

Any assertion supported in .blackfire.yaml, based on built-in and/or custom metrics, can be added this way.

Using Blackfire Environment Variables

You can use assertions variables, defined in the Blackfire environment, like you would do within assertions defined in .blackfire.yaml file:

1
2
3
4
5
6
scenario
    # no Twig template compilation in production
    # not enforced in other environments
    visit url('/blog/')
        name "Blog homepage"
        assert main.peak_memory < 10mb * var('memory_coeff')

Builds Comparison

To make some comparisons with a previous build, you can set the external_id and external_parent_id settings of the build by passing BLACKFIRE_EXTERNAL_ID and BLACKFIRE_EXTERNAL_PARENT_ID environment variables:

1
2
3
BLACKFIRE_EXTERNAL_ID=current_build_reference \
BLACKFIRE_EXTERNAL_PARENT_ID=parent_build_reference \
blackfire-player run scenario.bkf --blackfire-env=ENV_NAME_OR_UUID

Other Supported Instructions

Samples

The samples instruction tells Blackfire Profiler how many samples must be aggregated for a single profile. The default value is 1.

Warmup

The warmup instruction tells Blackfire Profiler whether to warmup the requested URL first.

Its value can be:

  • true: Warmups safe HTTP requests, or when the number of samples is more than one. Warmup will be executed 3 times. (default value)
  • A number: Same behavior as true, but allows to change the number of warmup requests.
  • false: Disables warmup
1
2
3
4
5
6
scenario
    visit url('/blog/')
        name "Blog homepage"
        assert main.peak_memory < 10M
        samples 2
        warmup true