1. Documentation
  2. Profiling Cookbooks
  3. Profiling CLI Commands

Profiling CLI Commands

Blackfire can profile any code that you need to run on the command line thanks to the blackfire utility that is bundled with the Blackfire Agent.

Profiling Simple CLI Scripts

Profiling a PHP script is a matter of prefixing your command with blackfire run:

1
2
$ 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 -q option.)

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):

1
$ blackfire --samples 10 run php my-script.php

Warning

Recommended: To explicitly define which environment the profile must be sent to, use the --env=<ENV_UUID> parameter.

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 profile.

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_ID and BLACKFIRE_CLIENT_TOKEN) were used. Only that user can then access the profile from /my/profiles.

To explicitly specify your personal sandbox environment, use --env="My Environment"

JSON Output

You can integrate Blackfire results into your tools by using the --json option to get a JSON representation of a profile:

1
$ blackfire --json run php my-script.php

Note

The JSON output is displayed on STDOUT, while the regular output (e.g. progress, profile summary…) is displayed on STDERR.

The resources consumed are available under the envelope entry; keys are the dimensions:

  • pmu: Peak Memory Usage (in bytes);
  • nw: Network (in bytes);
  • wt: Wall Clock Time (in microseconds);
  • cpu: CPU time (in microseconds);
  • io: I/O time (in microseconds).

Specifying the Target Environment

When using blackfire run within a Development or Production subscription, you can share the profiling result with your team. To do so, you will need to specify the targeted environment with the --env option:

1
$ blackfire --env <env-uuid> run php my-script.php

Profiling Part of a CLI Script

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 no-ops.

Profiling Consumers and Daemons

Consumers and Daemons are special as they run for a very long time (or indefinitely for daemons). In that case, using automatic instrumentation and the blackfire utility cannot work. Fortunately, the PHP SDK provides an abstraction that lets you profile consumers and daemons.