Agent Configuration

The Blackfire agent can be configured via a configuration file, flags passed to the binary, or environment variables.

Configuring the Agent via a Configuration File

The location of the default 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: /usr/local/etc/blackfire/agent;
  • On Windows: C:\ProgramData\blackfire\agent.ini.

The most important entries are server-id and server-token. Here is a typical configuration for the Agent that you can use as a template:

 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
49
50
51
52
53
[blackfire]
;
; setting: server-id
; desc   : Sets the server id used to authenticate with Blackfire
; default:
;
; You can find your personal server-id at https://blackfire.io/my/settings/credentials
server-id=<YOUR_SERVER_ID>

;
; setting: server-token
; desc   : Sets the server token used to authenticate with Blackfire. It is unsafe to set this from the command line
; default:
;
; You can find your personal server-token at https://blackfire.io/my/settings/credentials
server-token=<YOUR_SERVER_TOKEN>

;
; 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: socket
; desc   : Sets the socket the agent should read traces from. Possible value can be a unix socket or a TCP address
;
; default Linux:
; socket=unix:///var/run/blackfire/agent.sock
;
; default macOS:
; unix:///usr/local/var/run/blackfire-agent.sock
;
; default Windows:
; socket=tcp://127.0.0.1:8307

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

Warning

On Linux machines, setups using our packages also use an additional /etc/default/blackfire-agent configuration file. This allow service startup scripts to check settings and create directories or fix permissions if required.

On those configurations, you need to tweak this file to change the socket or the log target.

Here is the default content for this file:

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

Configuring the Agent via Environment Variables

The Agent can also be configured using environment variables:

  • BLACKFIRE_SERVER_ID / BLACKFIRE_SERVER_TOKEN

    Sets the server id and server token used to authenticate with Blackfire

    or to display your Blackfire's credentials.
  • BLACKFIRE_LOG_LEVEL

    Sets the verbosity of Agent’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 Agent’s log. Default value is stderr.

    1
    BLACKFIRE_LOG_FILE="/tmp/blackfire-agent.log"
    
  • BLACKFIRE_CONFIG

    Sets the location of the configuration file

    1
    BLACKFIRE_CONFIG="/dev/null"
    
  • BLACKFIRE_SOCKET

    Sets the socket the Agent will listen for the probes 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_SOCKET="unix:///var/run/blackfire/agent.sock"
    

    On macOS:

    1
    BLACKFIRE_SOCKET="unix:///usr/local/var/run/blackfire-agent.sock"
    

    On Windows:

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

    On Docker, it is suggested to use this value:

    1
    BLACKFIRE_SOCKET="tcp://0.0.0.0:8307"
    
  • BLACKFIRE_COLLECTOR

    Sets the URL of Blackfire’s data collector. Default value is https://blackfire.io.

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

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_SERVER_ID=xxx
export BLACKFIRE_SERVER_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/agent.log

Running the Agent Behind an HTTP(s) Proxy

Warning

If you are behind a proxy, define the HTTP_PROXY and/or HTTPS_PROXY environment variables or add the following options to the command: --http-proxy and/or --https-proxy.