Configuration PHP¶

Configuring the Probe via Environment Variables¶

It’s preferable that you configure the PHP probe using environment variables. It allows you to change the configuration without modifying your code. You can use the following environment variables:

• BLACKFIRE_CLIENT_ID / BLACKFIRE_CLIENT_TOKEN

  Sets the client ID and client Token used to authenticate with Blackfire.

  Login or Sign Up to display your Blackfire credentials.

• BLACKFIRE_LOG_LEVEL

  Sets the verbosity of the Probe’s log output. Default value is 1 (error).

  1 2 3 4 5

  # 1: error # 2: warning # 3: info # 4: debug BLACKFIRE_LOG_LEVEL=1

• BLACKFIRE_LOG_FILE

  Defines where the output of the probe logs is sent. Default value is empty.

  1	BLACKFIRE_LOG_FILE="/tmp/probe.log"

• BLACKFIRE_DEBUG_SIGSEGV_HANDLER

  Add the stacktrace to the probe logs when a segmentation fault occurs.

  Default value is 0 (stacktrace not collected).

  This debug option is inactive on Windows and Alpine.

  1	BLACKFIRE_DEBUG_SIGSEGV_HANDLER=0

• BLACKFIRE_AGENT_SOCKET

  Defines which socket the Probe contacts the Agent on. Possible values can be a Unix socket or a TCP address.

  The default value is platform dependent, as detailed below.

  On Linux:

  1	BLACKFIRE_AGENT_SOCKET="unix:///var/run/blackfire/agent.sock"

  On macOS:

  1 2 3 4 5

  # amd64 BLACKFIRE_AGENT_SOCKET="unix:///usr/local/var/run/blackfire-agent.sock" # arm64 (M1) BLACKFIRE_AGENT_SOCKET="unix:///opt/homebrew/var/run/blackfire-agent.sock"

  On Windows:

  1	BLACKFIRE_AGENT_SOCKET="tcp://127.0.0.1:8307"

• BLACKFIRE_ENDPOINT

  Defines which API endpoint the profile data is sent to.

  1	BLACKFIRE_ENDPOINT="https://blackfire.io"

• BLACKFIRE_APM_ENABLED

  Enables or disables Blackfire Monitoring.

  1	BLACKFIRE_APM_ENABLED=1

• BLACKFIRE_SERVER_ID / BLACKFIRE_SERVER_TOKEN

  Sets the server ID and server Token used to authenticate with Blackfire. This is optional. Prefer configuring your server credentials in the Agent.

  Login or Sign Up to display your Blackfire credentials.

You can set these environment variables in the local .env file of your project if supported. Alternatively, you can set them in your global shell configuration file (such as ~/.bashrc or ~/.zshrc):

1
2
3
4

export BLACKFIRE_CLIENT_ID=xxx
export BLACKFIRE_CLIENT_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/probe.log

Configuring the Probe via the Blackfire CLI Client Configuration File¶

When environment variables are not set, the probe reads its default configuration from the configuration of the Blackfire CLI client. The location of this file depends on the operating system you use. Read more about the CLI configuration.

Configuring the Probe via the php.ini Configuration File¶

You can also configure the PHP probe via 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
31
32
33
34
35
36
37
38
39
40
41

[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll

; 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 =

; 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

; Add the stacktrace to the probe logs when a segmentation fault occurs.
; Debug option inactive on Windows and Alpine.
;blackfire.debug.sigsegv_handler = 0

; Sets the socket where the agent is listening.
; Possible value can be a unix socket or a TCP address.
; Defaults values are:
;   - Linux: unix:///var/run/blackfire/agent.sock
;   - macOS amd64: unix:///usr/local/var/run/blackfire-agent.sock
;   - macOS arm64 (M1): unix:///opt/homebrew/var/run/blackfire-agent.sock
;   - Windows: tcp://127.0.0.1:8307
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

; Enables Blackfire Monitoring
; Enabled by default since version 1.61.0
;blackfire.apm_enabled = 1

Configuring the Probe via the Web Server Configuration¶

Make sure you configure your server credentials blackfire.server_id and blackfire.server_token in the agent. Only configure your server credentials on a virtual host-by-virtual host basis if you meet one of the following sets of requirements:

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

location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=<YOUR_BLACKFIRE_SERVER_ID>
    blackfire.server_token=<YOUR_BLACKFIRE_SERVER_TOKEN>
";
}

1
2
3
4
5
6

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

<VirtualHost 192.168.42.43>
    ServerName www.myvhost1.com
    DocumentRoot "/path/to/vhost1/"
    ...
    # PHP 5
    <IfModule mod_php5.c>
        php_admin_value[blackfire.server_id] = "<YOUR_BLACKFIRE_SERVER_ID>"
        php_admin_value[blackfire.server_token] = "<YOUR_BLACKFIRE_SERVER_TOKEN>"
    </IfModule>

    # PHP 7
    <IfModule mod_php7.c>
        php_admin_value[blackfire.server_id] = "<YOUR_BLACKFIRE_SERVER_ID>"
        php_admin_value[blackfire.server_token] = "<YOUR_BLACKFIRE_SERVER_TOKEN>"
    </IfModule>

    # PHP 8+
    <IfModule mod_php.c>
        php_admin_value[blackfire.server_id] = "<YOUR_BLACKFIRE_SERVER_ID>"
        php_admin_value[blackfire.server_token] = "<YOUR_BLACKFIRE_SERVER_TOKEN>"
      </IfModule>
</VirtualHost>

[website1]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "<YOUR_BLACKFIRE_SERVER_ID>"
php_admin_value blackfire.server_token "<YOUR_BLACKFIRE_SERVER_TOKEN>"

[website2]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "<YOUR_BLACKFIRE_SERVER_ID>"
php_admin_value blackfire.server_token "<YOUR_BLACKFIRE_SERVER_TOKEN>"