Configuration PHP¶

Configuring the Probe via Environment Variables¶

The preferred way to configure the PHP probe is via environment variables. That allows you to change the configuration without modifying your code:

• BLACKFIRE_CLIENT_ID

  Sets the client ID from the Client ID/Client Token credentials pair.

  Login or Sign Up to display your Blackfire's credentials.

• BLACKFIRE_CLIENT_TOKEN

  Sets the client Token from the Client ID/Client Token credentials pair.

  Login or Sign Up to display your Blackfire's credentials.

• BLACKFIRE_LOG_LEVEL

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

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

• BLACKFIRE_LOG_FILE

  Sets the output destination of Probe’s log. Default value is empty.

  1	BLACKFIRE_LOG_FILE="/tmp/probe.log"

• BLACKFIRE_AGENT_SOCKET

  Sets the socket the Probe will contact 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

  Sets the API endpoint the profile data will be 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, and should be used only if you have a shared agent between multiple environments.

  Login or Sign Up to display your Blackfire's credentials.

You can set these environment variables in a project’s local .env file if supported, or 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¶

The PHP probe can also be configured via the 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

[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

; 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 macOS amd64,
; unix:///opt/homebrew/var/run/blackfire-agent.sock on macOS arm64 (M1),
; and to tcp://127.0.0.1:8307 on Windows.
;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¶

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 criterion, the following sections tell you how to better control the server credentials per vhost.

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"