Symfony Messenger helps applications send and receive messages. Integrating Blackfire with Symfony Messenger lets you monitor your Message Handlers and track individual message processing.
You must, first, enable monitoring on your environment.
Automatic monitoring of Messenger workers is in beta and opt-in.
The Probe monitors your messenger:consume workers with a single
setting, without any middleware or code change:
1
blackfire.apm_cli_workers = 1
You can also use an environment variable:
1
$ BLACKFIRE_APM_CLI_WORKERS=1 php bin/console messenger:consume async
blackfire.observer_api enabled (the default);cli SAPI;When a worker runs on the cli SAPI but another requirement is missing, the
Probe ignores the setting and logs a message at the info level. Set
blackfire.log_level to 3 or higher to see it.
RedispatchMessage
uses the name of the wrapped message, RunCommandMessage the command name,
and a Scheduler ServiceCallMessage the service and method
(@service::method). Each scheduled task gets its own name.(forward) suffix, so it does not mix with the transaction of the
worker that handles the message.You can keep the setting enabled for all CLI commands. Commands that do not run a Messenger worker are not affected and do not contact the Agent.
Symfony Messenger 8.2+ handles messages in parallel with the --concurrency
option:
1
$ php bin/console messenger:consume async --concurrency=4
The parent process dispatches messages to its children and sends no transaction. Each child sends one transaction per message it handles.
Monitoring concurrent workers requires Blackfire PHP Probe 2026.10.3 or later and PHP 8.4 or later, which Symfony Messenger 8.2 also requires.
By default, children run as separate PHP processes and do not inherit
php -d options. The following command monitors nothing:
1
$ php -d blackfire.apm_cli_workers=1 bin/console messenger:consume async --concurrency=4
Enable the setting in php.ini or with the BLACKFIRE_APM_CLI_WORKERS=1
environment variable instead. Children started as ext-parallel threads
inherit -d options.
php-cli.To report a gap during the beta, open a ticket on the Blackfire support site.
If you monitor your workers with the MonitoredMiddleware, automatic
monitoring replaces it with a single setting instead of one middleware per bus.
Keep the middleware if your workers run PHP 8.1 or earlier.
Enable blackfire.apm_cli_workers on your workers:
1
blackfire.apm_cli_workers = 1
Remove the middleware from every bus, and remove its service definition:
1 2 3 4 5 6 7 8 9
framework:
messenger:
buses:
messenger.bus.default:
middleware:
- - 'Blackfire\Bridge\Symfony\MonitoredMiddleware'
-services:
- Blackfire\Bridge\Symfony\MonitoredMiddleware: ~
blackfire/php-sdk dependency if nothing else in your project
uses it.RedispatchMessage, RunCommandMessage and Scheduler
ServiceCallMessage transactions take the name of the work they carry.
Update the filters that rely on the old names.On PHP 8.2 or later, automatic monitoring needs no middleware. See Symfony Messenger [language: PHP].
Add Blackfire PHP SDK as a dependency in your project (1.27+ version).
The Blackfire PHP SDK provides a Symfony Messenger middleware that eases collecting and measuring the processing of your messages:
1 2 3 4 5 6 7 8 9
framework:
messenger:
buses:
messenger.bus.default:
middleware:
- 'Blackfire\Bridge\Symfony\MonitoredMiddleware'
services:
Blackfire\Bridge\Symfony\MonitoredMiddleware: ~
A transaction name is generated for every processed message given the class name of the message. It allows monitoring of consumers given message types.
Transactions are visible on the Monitoring dashboard page, filtering on CLI
requests.