CLI Configuration ¶

The Blackfire CLI is configured by default with a .blackfire.ini file that can be found:

• in $BLACKFIRE_HOME/.blackfire.ini if you have defined the $BLACKFIRE_HOME environment variable;
• On Linux systems, in $XDG_CONFIG_HOME/.blackfire.ini;
• On all systems, in $HOME/.blackfire.ini;
• On Windows systems, in $HOMEDRIVE/$HOMEPATH/.blackfire.ini.

The most important entries are client-id and client-token. Here is a typical configuration for the CLI 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

[blackfire]
;
; setting: client-id
; desc   : Sets the Client ID used for API authentication
; default:
client-id=<YOUR_CLIENT_ID>

;
; setting: client-token
; desc   : Sets the Client Token used for API authentication
; default:
client-token=<YOUR_CLIENT_TOKEN>

;
; setting: http-proxy
; desc   : Sets the HTTP proxy to use
; default:
; http-proxy=

;
; setting: https-proxy
; desc   : Sets the HTTPS proxy to use
; default:
; https-proxy=

;
; setting: endpoint
; desc   : Sets the API endpoint
; default: https://blackfire.io
; endpoint=https://blackfire.io

;
; setting: timeout
; desc   : Sets the Blackfire API connection timeout
; default: 15s
; timeout=15s

;
; setting: ca-cert
; desc   : Sets the PEM encoded certificates to use
; default:
; ca-cert=

The CLI can also be configured using environment variables:

• BLACKFIRE_CLIENT_ID / BLACKFIRE_CLIENT_TOKEN

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

  Loading...

• 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_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

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