Agent Configuration (v2)¶

Configuring the Agent via a Configuration File¶

The location of the default agent configuration file depends on your platform:

• On Linux: /etc/blackfire/agent;
• On macOS: * Intel Macs: /usr/local/etc/blackfire/agent; * Apple Silicon Macs: /opt/homebrew/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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

[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: memory-limit
; desc   : Sets the maximum allowed RAM usage (megabytes) when ingesting traces. Use 0 to disable
; default: 500
memory-limit=500

;
; 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 amd64:
; unix:///usr/local/var/run/blackfire-agent.sock
;
; default macOS arm64 (M1):
; unix:///opt/homebrew/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

;
; setting: statsd
; desc   : Sets the statsd server to send agent's statistics to. ie: udp://host:port. Leave empty to disable.
; default:
; statsd=

;
; setting: statsd-prefix
; desc   : Sets the statsd prefix to use when sending data
; default: blackfire
; statsd-prefix=blackfire

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.

  Login or Sign Up 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_MEMORY_LIMIT

  Sets the maximum allowed RAM usage (megabytes) when ingesting traces. Use 0 to disable.

  1	BLACKFIRE_MEMORY_LIMIT=500

• 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 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 and Kubernetes:

  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"

• BLACKFIRE_STATSD

  Sets the statsd server to send agent’s statistics to. ie: udp://host:port.

  1	BLACKFIRE_STATSD="udp://host:port"

• BLACKFIRE_STATSD_PREFIX

  Sets the statsd prefix to use when sending data. Default value is blackfire.

  1	BLACKFIRE_STATSD_PREFIX="blackfire"

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¶

Those environment variables can be added to a docker-compose.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

  version: '3'
  services:
    blackfire:
      image: blackfire/blackfire:2
      ports: ["8307"]
      environment:
          # Exposes BLACKFIRE_* environment variables from the host
          BLACKFIRE_SERVER_ID: ~
          BLACKFIRE_SERVER_TOKEN: ~
          BLACKFIRE_CLIENT_ID: ~
          BLACKFIRE_CLIENT_TOKEN: ~
          HTTP_PROXY: "<your_proxy_address>"
          HTTPS_PROXY: "<your_proxy_address>"

If the Agent is launched by systemd, the environment variables can be defined by editing the blackfire-agent service:

• Run sudo systemctl edit blackfire-agent
• Edit the configuration and save the file:

1
2
3

[Service]
Environment="HTTP_PROXY=<your_proxy_address>"
Environment="HTTPS_PROXY=<your_proxy_address>"

• Run sudo systemctl daemon-reload
• Run sudo systemctl restart blackfire-agent