Configuration

Agent Configuration

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

  • On Linux: /etc/blackfire/agent
  • 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 API
; default:
server-id=d8108598-7a7a-4c5e-8f03-d0bccadc0931

;
; setting: server-token
; desc   : Sets the server token used to authenticate with Blackfire API. 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=

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
[blackfire]
extension="/path/to/installed/extension/blackfire.so"

; 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

;blackfire.server_id =

;blackfire.server_token =

Note

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

Caution

When configuring the Probe via php.ini, the server credentials (server id and server token) are 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.

Probe Fine-Grained Configuration

In the previous section, you learned how to configure all websites hosted on a server by setting the blackfire.server_id and blackfire.server_token in php.ini. The following sections tell you how to better control the credentials on a per-host/per-directory basis.

We recommend that you always set some "default" credentials in php.ini as they will 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"

Reverse Proxy

If there is a reverse proxy such as Varnish or HA Proxy between your browser and the profiled website, you will probably want:

  • To serve a non-cached version from the reverse proxy;
  • To not remove the special HTTP headers injected by the browser extension;
  • To target a specific server behind the proxy.

Blackfire browser extension uses a unique HTTP header for its requests: X-Blackfire-Query.

You also need to be sure that the following HTTP response headers are preserved: X-Blackfire-Response and X-Blackfire-Error

Here's a varnish configuration sample:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
acl profile {
   "x.y.z.w";
}

sub vcl_recv {
  if (req.http.X-Blackfire-Query && client.ip ~ profile) {
    if (req.esi_level > 0) {
        # ESI request should not be included in the profile.
        # Instead you should profile them separately, each one
        # in their dedicated profile.
        # Removing the Blackfire header avoids to trigger the profiling.
        # Not returning let it go trough your usual workflow as a regular
        # ESI request without distinction.
        unset req.http.X-Blackfire-Query;
    } else {
        return (pass);
    }
  }
}

Load Balancer

If you're using multiple PHP servers behind a load-balancer for your application, you have two choices to profile it:

  • The first and recommended option is to:
  • Install the Blackfire Probe and the Blackfire Agent on a single PHP server;
  • Configure the load balancer to route all requests containing headers matching X-Blackfire-Query to the configured PHP server;
  • The second option is to:
  • setup a single Blackfire Agent for all the PHP servers and configure it to listen on the network using a TCP socket:

    1
    socket=tcp://0.0.0.0:8307
    
  • setup the Blackfire Probe on all the PHP servers and configure it using the TCP socket defined above in the probe.ini configuration:

    1
    blackfire.agent_socket = tcp://10.0.0.1:8307
    

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