blackfire

Initialize and configure the Blackfire client

Launch the Blackfire agent
Launch the Blackfire agent on a specific socket
Run the profiler on a specific program
Run the profiler and collect 10 samples
Run the profiler and output results as JSON
Upload a profiler file to the Blackfire web service
View the status of profiles on the Blackfire web service

blackfire <command> [options] [arguments]

This is a simplified representation. The blackfire command typically operates with subcommands, each having its own specific options and arguments.

Common subcommands and their general usage include:

• blackfire profile [options] <URL>: Profiles a web request by sending an HTTP request to the specified URL.
• blackfire run [options] <command>: Profiles a local command-line script or application process.
• blackfire agent [options]: Manages or interacts with the Blackfire Agent service.
• blackfire config [options]: Manages Blackfire client and agent configuration settings.
• blackfire inspect <UUID>: Retrieves details and data for a specific profile identified by its UUID.
• blackfire help [command]: Displays help information for the main command or a specific subcommand.

--agent=<addr>
    (Global) Specifies the Blackfire Agent's address (e.g., 'tcp://127.0.0.1:8307' or 'unix:///var/run/blackfire/agent.sock'). This overrides the default agent discovery.

--auth=<client_id>:<client_token>
    (Global) Provides the Blackfire client credentials directly for authentication, overriding environment variables or configuration files.

--debug
    (Global) Enables highly verbose debugging output, useful for diagnosing issues with the Blackfire CLI or its interaction with the agent/probe.

--json
    (Global) Outputs results in JSON format, suitable for programmatic parsing and integration into automated workflows.

--version
    (Global) Displays the current version of the Blackfire CLI tool.

--verbose
    (Global) Increases the verbosity of messages, providing more detailed information about the command's execution.

--output=<file>
    (Profile/Run) Saves the raw profile data or a generated report to the specified file path instead of sending it to Blackfire.io or printing to stdout.

--format=<format>
    (Profile/Run) Specifies the output format for the profile report when using --output (e.g., 'html', 'json', 'callgrind', 'dot', 'svg').

--aggregate
    (Profile/Run) When profiling multiple times (e.g., using --iterations), this option aggregates the collected data from all runs into a single, comprehensive profile.

--env=<name>
    (Profile/Run) Specifies the Blackfire environment (defined on Blackfire.io) to associate the generated profile with. Useful for organizing profiles across different application stages.

--title=<title>
    (Profile/Run) Assigns a custom, human-readable title to the generated profile, making it easier to identify on the Blackfire.io dashboard.

--php=<path>
    (Run) Specifies the path to the PHP executable that should be used when profiling PHP CLI commands with blackfire run.

--php-ini=<path>
    (Run) Specifies an additional PHP INI file to be loaded by the PHP executable during profiling, allowing custom runtime configurations.

--disable-php-ini
    (Profile/Run) Prevents Blackfire from loading default PHP INI files during profiling. Useful for ensuring a clean, isolated profiling environment.

The blackfire command-line tool is the primary interface for interacting with the Blackfire.io performance management service. It enables developers and operations teams to profile web applications to identify performance bottlenecks, optimize code, and monitor application health. Blackfire works by deploying a lightweight agent on the server and a probe within the application's runtime environment (e.g., PHP-FPM, Node.js process). The CLI tool acts as a companion, orchestrating the profiling process: it triggers a request to the application, the probe collects data, sends it to the agent, which then forwards it to the Blackfire.io cloud for analysis and visualization.

Beyond on-demand profiling, Blackfire supports continuous profiling, integration with CI/CD pipelines, and automated performance assertions. This allows teams to detect performance regressions early in the development lifecycle, ensuring consistent application performance. It's widely used in the PHP ecosystem but also supports other languages like Python, Node.js, and Go.

Blackfire requires a Blackfire.io account and proper setup, including the Blackfire Agent running on the server and the Blackfire Probe installed within the application's runtime environment (e.g., PHP-FPM extension).
The tool needs network connectivity to the Blackfire.io cloud service for profile analysis and storage.
While profiling, there is a minimal performance overhead on the application being profiled, which is typical for profiling tools.
It is primarily designed for web application performance profiling, focusing on execution paths triggered by HTTP requests or CLI commands, rather than general system-wide performance monitoring.

The Blackfire ecosystem relies on three core components: the Blackfire Agent (a daemon collecting data), the Blackfire Probe (an application extension gathering runtime data), and the Blackfire Companion CLI (the blackfire command, which orchestrates profiling sessions).
Blackfire also introduces concepts like Assertions (rules to validate performance metrics against predefined thresholds) and Scenarios (automated sequences of requests to profile specific user flows or functionalities).

One of Blackfire's strengths is its seamless integration into Continuous Integration and Continuous Delivery (CI/CD) pipelines. The blackfire CLI can be used in build scripts to automatically profile code changes, run performance assertions, and detect regressions before deployment. This proactive approach helps maintain application performance quality throughout the development lifecycle, ensuring that performance issues are caught early.

Blackfire was initially developed by SensioLabs, the company behind the Symfony PHP framework, and officially launched in 2014. Its roots are deeply embedded in the PHP ecosystem, providing a much-needed robust and developer-friendly profiling solution for PHP applications.

Over time, Blackfire expanded its language support to include Python, Node.js, Go, and Ruby, evolving into a more general-purpose web application profiler. A key focus has been on integrating profiling into CI/CD workflows, enabling 'continuous profiling' and automated performance testing. This shift allowed developers to proactively identify and fix performance issues before they reached production, moving beyond reactive post-deployment monitoring.

perf(1), strace(1), ltrace(1), gprof(1), top(1)