Blackfire can profile any code that you need to run on the command line thanks
blackfire utility that is bundled with the Blackfire Agent.
Profiling a PHP script is a matter of prefixing your command with
$ blackfire run php my-script.php $ blackfire run php my-script.php --your-script-options and arguments
At the end of the execution,
blackfire outputs the URL where the profile
can be found (this can be hidden by passing the
To get more accurate results, you can also take several samples via the
--samples option (only do that if you are sure that two successive calls to
your script do the same thing without unwanted side effects):
$ blackfire --samples 10 run php my-script.php
Recommended: To explicitly define which
environment the profile must be sent
to, use the
v2.14.0+ of the unified Agent and Client:
when no target environment is specified, the Agent uses the
BLACKFIRE_SERVER_ID environment variable to determine where to send the
When no target environment is specified or implicitly discovered, the profile
is sent to the personal sandbox environment of the user whose
personal credentials (
BLACKFIRE_CLIENT_TOKEN) were used. Only that user can then access
the profile from /my/profiles.
To explicitly specify your personal sandbox environment, use
You can integrate Blackfire results into your tools by using the
option to get a JSON representation of a profile:
$ blackfire --json run php my-script.php
The JSON output is displayed on
STDOUT, while the regular output (e.g.
progress, profile summary…) is displayed on
The resources consumed are available under the
envelope entry; keys are the
Blackfire automatically instruments your code, but sometimes, you might want to focus the profiling on only part of the code. That’s possible when opting for manual instrumentation via the PHP SDK.
After instrumenting your code, use the
blackfire utility as above to
profile your application. When not using Blackfire, all calls are converted to
Consumers and Daemons are special as they run for a very long time (or
indefinitely for daemons). In that case, using automatic instrumentation and
blackfire utility cannot work. Fortunately, the PHP SDK provides an abstraction that lets you profile
consumers and daemons.