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=

 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}"

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

[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

;blackfire.server_id =

;blackfire.server_token =

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 do not recommend that you set some "default" credentials in php.ini as the Agent ones will already be used as the default fallback.

1
2
3
4
5
6

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

1
2
3
4
5
6

location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=
    blackfire.server_token=
";
}

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>

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"

Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN)¶

If you have a reverse proxy, cache, or content delivery network (CDN) in front of your application, you will want to bypass it when profiling with Blackfire.

We provide an example below to describe which headers are sent and required to pass through to your application (and the Blackfire Probe) in order for Blackfire to successfully profile your application.

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

  Note

  Please note that using our packages on Linux, the socket configuration is defined in /etc/default/blackfire-agent. You can refer to the /etc/default/blackfire-agent section for more information.

• setup the Blackfire Probe on all the PHP servers and configure it using the TCP socket defined above in the php.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