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.
or Sign Up to display your Blackfire's credentials.
BLACKFIRE_CLIENT_TOKEN
Sets the client Token from the Client ID/Client Token credentials pair.
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.
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 |
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.
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 |
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
.
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.
Caution
There are only two use cases for fine-grained configuration. If neither of these use cases describes 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.
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.
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= "; } |
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> |
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 at the detailed documentation about reverse proxies in case your application is behind a cache server, a load balancer, or any other reverse proxy.