Configuration

Agent Configuration

The location of the agent configuration file depends on your platform:

  • On Linux: /etc/blackfire/agent (and /etc/default/blackfire-agent when launched as a daemon by the system)
  • On MacOS X: /usr/local/etc/blackfire/agent
  • On Windows: C:\ProgramData\blackfire\agent.ini

Here is a typical configuration for the Agent that you can use as a template for your own:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[blackfire]
;
; setting: ca-cert
; desc   : Sets the PEM encoded certificates
; default:
ca-cert=

;
; setting: collector
; desc   : Sets the URL of Blackfire's data collector
; default: https://blackfire.io
collector=https://blackfire.io

;
; setting: log-file
; desc   : Sets the path of the log file. Use stderr to log to stderr
; default: stderr
log-file=stderr

;
; setting: log-level
; desc   : log verbosity level (4: debug, 3: info, 2: warning, 1: error)
; default: 1
log-level=1

;
; setting: server-id
; desc   : Sets the server id used to authenticate with Blackfire
; default:
server-id=d8108598-7a7a-4c5e-8f03-d0bccadc0931

;
; setting: server-token
; desc   : Sets the server token used to authenticate with Blackfire. It is unsafe to set this from the command line
; default:
server-token=91bde3fa9350479ba84f90acab46b680142c0f6fe8154a649e82d0d2ddadfa93

;
; setting: socket
; desc   : Sets the socket the agent should read traces from. Possible value can be a unix socket or a TCP address
; default: unix:///var/run/blackfire/agent.sock on Linux, unix:///usr/local/var/run/blackfire-agent.sock on MacOSX, and tcp://127.0.0.1:8307 on Windows.
socket=unix:///var/run/blackfire/agent.sock

;
; setting: spec
; desc   : Sets the path to the JSON specifications file
; default:
spec=

Warning

On Linux machines, setups using our packages also use an additional /etc/default/blackfire-agent configuration file. This allow service startup scripts to check settings and create directories or fix permissions if required.

On those configurations, you need to tweak this file to change the socket or the log target.

Here is the default content for this file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# defaults socket for Blackfire Agent
SOURCEDIR="/var/run/blackfire"
SOURCE="unix://${SOURCEDIR}/agent.sock"

# Log file
LOG_FILE="/var/log/blackfire/agent.log"

# User under which the program will run
USER="blackfire"

# Arguments that will be given to the program when running it
DAEMON_ARGS="--log-file=${LOG_FILE} --socket=${SOURCE}"

Warning

If you are behind a proxy, define the HTTP_PROXY and/or HTTPS_PROXY environment variables or add the following options to the command: --http-proxy and/or --https-proxy.

Probe Global Configuration

Here is a typical configuration for the PHP probe that you can use as a template in your php.ini configuration file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll


; Sets the socket where the agent is listening.
; Possible value can be a unix socket or a TCP address.
; Defaults to unix:///var/run/blackfire/agent.sock on Linux,
; unix:///usr/local/var/run/blackfire-agent.sock on MacOSX,
; and to tcp://127.0.0.1:8307 on Windows.
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

blackfire.agent_timeout = 0.25

; Log verbosity level (4: debug, 3: info, 2: warning, 1: error)
;blackfire.log_level = 1

; Log file (STDERR by default)
;blackfire.log_file = /tmp/blackfire.log

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_id =

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_token =

Note

If you don't know where is your php.ini file located, execute this command: php --ini

Caution

We do not recommend configuring server credentials (server id and server token) via php.ini. For the vast majority of cases, the server credentials should only be set in the agent.

If you do configure server credentials via php.ini, they will be shared amongst all virtual hosts. Read the next section to learn more about how to configure different credentials on a per-host/per-directory basis.

Caution

There is only one use case for configuring server credentials via php.ini.

  1. You must have multiple Blackfire environments, with each individual server dedicated to one of the environments, and all servers are configured to communicate with the same agent.

Probe Fine-Grained Configuration

In the previous section, you learned it is possible to configure all websites hosted on a server by setting the blackfire.server_id and blackfire.server_token in php.ini. You also learned that we do not recommend this except under very specific conditions.

Like global-configuration via php.ini, there are specific use cases where it makes sense to configure Blackfire on a vhost-by-vhost basis. If you fit this criteria, the following sections tell you how to better control the server credentials per vhost.

Caution

There are only two use cases for fine-grained configuration. If neither of these use cases describe you, you should not attempt fine-grained probe configuration. For the vast majority of cases, the server credentials should only be set in the agent.

  1. You must have multiple Blackfire environments, multiple virtual hosts on a server, and you want to assign specific Blackfire environments to specific virtual hosts.
  2. You must have one or more Blackfire environments, multiple virtual hosts on a server, and you want to only allow Blackfire profiling on a subset of your virtual hosts.

Caution

We do not recommend that you set some "default" credentials in php.ini as the Agent ones will already be used as the default fallback.

Nginx Configuration Settings

You can override the default credentials of the Probe in the Nginx configuration via the http, server and location sections. For more information, see Nginx documentation.

1
2
3
4
5
6
location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=e0b30241-a25d-4162-9ebb-329f784f1fc7
    blackfire.server_token=3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1
";
}

Note

Be warned that you must configure all hosts served by a PHP FPM pool.

Tip

If you want a host to use the default credentials, pass empty values:

1
2
3
4
5
6
location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=
    blackfire.server_token=
";
}

Apache Configuration Settings

You can override the default credentials of the Probe in the main Apache virtual-host configuration or by using a .htaccess file.

Use the following example to adjust your configuration, see PHP documentation for more information.

1
2
3
4
5
6
7
8
9
<VirtualHost 192.168.42.43>
    ServerName www.myvhost1.com
    DocumentRoot "/path/to/vhost1/"
    ...
    <IfModule mod_php5.c>
        php_admin_value blackfire.server_id "e0b30241-a25d-4162-9ebb-329f784f1fc7"
        php_admin_value blackfire.server_token "3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1"
    </IfModule>
</VirtualHost>

PHP-FPM Pool Configuration Settings

You can override the default credentials of the Probe per PHP-FPM pool. Open the php-fpm.conf and adjust settings given the following example. See the FPM documentation for more information.

1
2
3
4
5
6
7
8
9
[website1]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "b5f6c549-93c6-4118-a549-cf97f9effd54"
php_admin_value blackfire.server_token "5e5bc139f76c9c45ffbe7463fadaff2eb8d8ce8fcf172941fc881802445abc52"

[website2]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "e0b30241-a25d-4162-9ebb-329f784f1fc7"
php_admin_value blackfire.server_token "3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1"

Note

Please have a look to the detailed documentation about reverse proxies in case your application is behind a cache server, a load balancer or any other reverse proxy.

Content Security Policy

The browser extension injects a toolbar in the profiled webpage and uses an <iframe> to communicate with the PHP extension.

In case the web page declares a Content Security Policy regarding frames usage, the communication may be broken and you would be informed in the toolbar.

In this case, you can declare Blackfire domain as trusted by adding the blackfire.io domain in your application's headers:

1
Content-Security-Policy: frame-src 'self' blackfire.io
Support