Symfony Messenger
PHP

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 PHP Probe 2026.10.1 or later;
  • PHP 8.2 or later, with blackfire.observer_api enabled (the default);
  • the cli SAPI;
  • no Suhosin or Snuffleupagus extension, as both lock the Probe.

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.

  • Blackfire creates one transaction per message, named after the message class.
  • Wrapper messages take the name of the work they carry: 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.
  • When a worker only forwards a received message to another transport, like a Scheduler task routed to a transport or an outbox relay, the transaction name gets a (forward) suffix, so it does not mix with the transaction of the worker that handles the message.
  • Blackfire creates one transaction per batch handler flush, named after the handler class. When several batch handlers of the same message flush together, the name lists their classes.
  • Blackfire measures peak memory per message, not for the whole worker process.
  • Blackfire samples messages like web requests. Monitoring does not report errors for CLI transactions, so a failed message appears like a successful one.

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.

  • Blackfire does not monitor workers started with FrankenPHP php-cli.
  • When a handler starts an external program, such as ffmpeg or Ghostscript, Blackfire measures the time spent waiting for it, but not its memory and CPU usage.

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.

  1. Upgrade the Blackfire PHP Probe to 2026.10.1 or later, or 2026.10.3 or later for concurrent workers.
  2. Enable blackfire.apm_cli_workers on your workers:

    1
    blackfire.apm_cli_workers = 1
  3. Deploy. You can keep the middleware during the rollout: Blackfire still creates one transaction per message, not two.
  4. 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: ~
  5. Remove the blackfire/php-sdk dependency if nothing else in your project uses it.
  • Blackfire monitors every bus, including buses where you never added the middleware.
  • RedispatchMessage, RunCommandMessage and Scheduler ServiceCallMessage transactions take the name of the work they carry. Update the filters that rely on the old names.
  • Durations increase slightly, because a transaction covers the whole message handling, including worker event listeners and every middleware, not only what runs after the Blackfire middleware.
  • Memory values drop, because Blackfire measures peak memory per message instead of for the whole worker process.
  • Batch handler flushes appear as separate transactions.

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.