1. Documentation
  2. Getting Up and Running
  3. Configuration
  4. CLI Configuration

CLI Configuration

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

Configuring the CLI via a Configuration File

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=

Configuring the CLI via Environment Variables

The CLI can also be configured using environment variables:

  • BLACKFIRE_CLIENT_ID

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

    or to display your Blackfire's credentials.

    BLACKFIRE_CLIENT_ID=<YOUR_BLACKFIRE_CLIENT_ID>

  • BLACKFIRE_CLIENT_TOKEN

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

    or to display your Blackfire's credentials.

    BLACKFIRE_CLIENT_TOKEN=<YOUR_BLACKFIRE_CLIENT_TOKEN>

  • 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