How to use the command blackfire (with examples)

Blackfire is a command-line profiling tool for PHP. It allows developers to profile their PHP applications and gather performance information. The command blackfire provides various options to initialize, configure, launch the Blackfire agent, and run the profiler on specific programs.

Use case 1: Initialize and configure the Blackfire client

Code:

blackfire config

Motivation: Configuring the Blackfire client is necessary before using it for profiling. This command sets up the necessary configuration files and credentials.

Explanation: The config subcommand is used to initialize and configure the Blackfire client. It sets up the necessary configuration files that define the Blackfire authentication credentials, such as the token and server. Running this command ensures that the Blackfire client is ready to be used.

Example output:

Blackfire client successfully configured.

Use case 2: Launch the Blackfire agent

Code:

blackfire agent

Motivation: The Blackfire agent needs to be running in order to start profiling applications. This command launches the Blackfire agent on the default socket.

Explanation: The agent subcommand is used to launch the Blackfire agent, which listens for incoming profiling requests. By default, it starts the agent on the local machine on the default socket (tcp://127.0.0.1:8707). This command ensures that the Blackfire agent is running and ready to receive profiling requests.

Example output:

Blackfire agent successfully launched on socket tcp://127.0.0.1:8707.

Use case 3: Launch the Blackfire agent on a specific socket

Code:

blackfire agent --socket="tcp://127.0.0.1:8307"

Motivation: In some cases, it might be necessary to run the Blackfire agent on a specific socket. This command allows you to specify a custom socket for the Blackfire agent.

Explanation: The agent subcommand accepts a --socket option to specify a custom socket for the Blackfire agent. In the provided example, the Blackfire agent will be launched on tcp://127.0.0.1:8307, as opposed to the default socket. This command is useful when there are conflicts with existing services running on the default socket.

Example output:

Blackfire agent successfully launched on socket tcp://127.0.0.1:8307.

Use case 4: Run the profiler on a specific program

Code:

blackfire run php path/to/file.php

Motivation: Profiling a specific PHP program allows developers to gather performance information and identify bottlenecks or areas of improvement.

Explanation: The run subcommand is used to run the profiler on a specific PHP program. In the provided example, the profiler will be executed on the PHP file located at path/to/file.php. The php argument specifies the PHP executable to use for the profiling. This command generates a profile result of the program’s execution.

Example output:

Executing blackfire run on path/to/file.php...
Profile result generated: blackfire-1234abcdef

Use case 5: Run the profiler and collect 10 samples

Code:

blackfire --samples=10 run php path/to/file.php

Motivation: Collecting multiple samples increases the accuracy of the profiling results. Running the profiler with multiple samples can help identify performance patterns and anomalies.

Explanation: The --samples option is used to specify the number of samples to collect during profiling. In the provided example, the profiler will run on the PHP file located at path/to/file.php and collect 10 samples. This command provides a more comprehensive performance analysis by capturing multiple snapshots of the program execution.

Example output:

Executing blackfire run with 10 samples on path/to/file.php...
Profile result generated: blackfire-1234abcdef

Use case 6: Run the profiler and output results as JSON

Code:

blackfire --json run php path/to/file.php

Motivation: Outputting the profiling results as JSON allows for further analysis, integration with other tools, or automation of data processing.

Explanation: The --json option is used to output the profiling results in JSON format. In the provided example, the profiler will run on the PHP file located at path/to/file.php, and the results will be in JSON format. This command is useful when you need to programmatically process or integrate the profiling data with other tools or systems.

Example output:

{
  "profile_id": "blackfire-1234abcdef",
  "duration": 5.215,
  "memory": 102400,
  ...
}

Use case 7: Upload a profiler file to the Blackfire web service

Code:

blackfire upload path/to/file

Motivation: Uploading a profiler file to the Blackfire web service allows for centralized storage of profiling results and collaboration among team members.

Explanation: The upload subcommand is used to upload a profiler file to the Blackfire web service. In the provided example, the profiler file located at path/to/file will be uploaded. This command is useful when you want to share profiling results with others or store them centrally for future reference.

Example output:

Profiler file successfully uploaded: blackfire-1234abcdef

Use case 8: View the status of profiles on the Blackfire web service

Code:

blackfire status

Motivation: Checking the status of profiles on the Blackfire web service provides an overview of the captured profiling results and their associated metadata.

Explanation: The status subcommand is used to view the status of profiles on the Blackfire web service. This command retrieves and displays information about the profiles uploaded to the Blackfire web service, such as their IDs, duration, and memory usage. It gives developers an overview of the available profiles and helps them track the progress of their profiling activities.

Example output:

Profile status:
- blackfire-1234abcdef: duration=5.215s, memory=102400
- blackfire-5678ghijkl: duration=2.348s, memory=81920
...

Conclusion:

The blackfire command-line tool provides a comprehensive set of options and subcommands for initializing, configuring, launching the Blackfire agent, and running the profiler on PHP programs. Understanding these use cases helps developers efficiently utilize Blackfire for profiling and identifying performance bottlenecks in their PHP applications.