zenstruck / messenger-monitor-bundle
Batteries included UI to monitor your Messenger workers, transports, schedules, and messages.
Package info
github.com/zenstruck/messenger-monitor-bundle
Type:symfony-bundle
pkg:composer/zenstruck/messenger-monitor-bundle
Requires
- php: >=8.1
- symfony/framework-bundle: ^6.4.1|^7.0|^8.0
- symfony/messenger: ^6.4|^7.0|^8.0
- zenstruck/bytes: ^1.0
- zenstruck/collection: ^0.9
Requires (Dev)
- doctrine/doctrine-bundle: ^2.10|^3.0
- doctrine/orm: ^2.15|^3.1
- knplabs/knp-time-bundle: ^1.20|^2.0
- lorisleiva/cron-translator: ^0.4.3
- matthiasnoback/symfony-dependency-injection-test: ^4.3|^5.0|^6.0
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.6.0|^10.0
- symfony/config: ^6.4|^7.0|^8.0
- symfony/console: ^6.4|^7.0|^8.0
- symfony/http-client-contracts: ^3.3
- symfony/mailer: ^6.4|^7.0|^8.0
- symfony/phpunit-bridge: ^6.1|^7.0|^8.0
- symfony/process: ^6.4|^7.0|^8.0
- symfony/scheduler: ^6.4|^7.0|^8.0
- symfony/security-bundle: ^6.4|^7.0|^8.0
- symfony/serializer: ^6.4|^7.0|^8.0
- symfony/var-dumper: ^6.4|^7.0|^8.0
- zenstruck/console-test: ^1.5
- zenstruck/foundry: ^2.2
- zenstruck/messenger-test: ^1.11
Suggests
- knplabs/knp-time-bundle: For human readable timestamps and durations on your dashboard.
- lorisleiva/cron-translator: For human readable cron expressions on your dashboard.
Provides
None
Conflicts
None
Replaces
None
README
Batteries included UI to monitor your Messenger workers, transports, schedules, and messages.
| Dashboard | Message details |
|---|---|
![]() |
![]() |
| Failed transport | Schedules |
![]() |
![]() |
If the packaged UI is not to your liking, you can easily build your own with the provided tools.
- Installation
- Console monitor
- Storage and message history
- User interface
- Advanced usage
- Configuration reference
Installation
Requires PHP 8.1+ and Symfony 6.4 (6.4.1+), 7.x, or 8.x, with the PHP version required by your Symfony release.
composer require zenstruck/messenger-monitor-bundle
Symfony Flex registers the bundle automatically. Without Flex, add it to config/bundles.php:
return [ // ... Zenstruck\Messenger\Monitor\ZenstruckMessengerMonitorBundle::class => ['all' => true], ];
Worker and transport monitoring work immediately. Configure storage for message history and the user interface. See UPGRADE.md when upgrading.
messenger:monitor Command
With zero configuration, you can run the messenger:monitor command to see information
about your running workers and transports. If storage is configured, it displays a
historical snapshot whose period can be customized with the --period option.
bin/console messenger:monitor bin/console messenger:monitor --no-interaction # print once instead of refreshing every second bin/console messenger:monitor --period in-last-week # requires storage
The default history period is in-last-day. Use in-last-hour, in-last-day, in-last-week,
in-last-month, today, yesterday, last-week, last-month, or all.
Workers and the command must use the same cache pool.
Storage
Note
The User Interface and History require storage. Doctrine ORM is the supported storage engine.
Configuration
Install Doctrine ORM and migration tools if your app does not already have them:
composer require symfony/orm-pack
Configure your database connection before continuing.
-
Create a
ProcessedMessageentity that extendsZenstruck\Messenger\Monitor\History\Model\ProcessedMessagein your app:// src/Entity/ProcessedMessage.php namespace App\Entity; use Zenstruck\Messenger\Monitor\History\Model\ProcessedMessage as BaseProcessedMessage; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity(readOnly: true)] #[ORM\Table('processed_messages')] class ProcessedMessage extends BaseProcessedMessage { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; public function id(): ?int { return $this->id; } }
-
Add the entity class to the bundle config:
# config/packages/zenstruck_messenger_monitor.yaml zenstruck_messenger_monitor: storage: orm: entity_class: App\Entity\ProcessedMessage # entity_manager: custom
If you use a different entity manager, set
entity_managernext toentity_class. If you already set thezenstruck_messenger_monitor.history.orm_managercontainer parameter, it takes precedence over the bundle option. -
Clear Cache:
bin/console cache:clear
-
Create and execute the migration:
bin/console doctrine:migrations:diff bin/console doctrine:migrations:migrate
-
Restart your Messenger workers so they load the new configuration:
bin/console messenger:stop-workers
Your process manager should start replacement workers. Start
messenger:consumeagain yourself if you run workers manually.
Tip
For large message histories, index finished_at for pagination and time-based snapshots.
Index run_id to speed up retry lookups on the message details page. Add the relevant
attributes to your ProcessedMessage entity, then generate and run a migration.
#[ORM\Index(name: 'idx_processed_messages_finished_at', fields: ['finishedAt'])] #[ORM\Index(name: 'idx_processed_messages_run_id', fields: ['runId'])]
Usage
Once configured, messages dispatched to a transport and consumed by a Messenger worker are tracked. Each completed attempt produces a history entry, including failed attempts that Messenger will retry. Synchronous handling outside a worker is not recorded.
History includes the message class, description, tags, transport, timestamps, wait and handling times, memory usage, handler results, and failures. View it in the user interface or query it with the history tools.
If result normalization or history storage fails, the history entry is skipped and an error is logged when a logger is available. Messenger continues acknowledging or retrying the message according to its handler outcome.
Note
Messages sent through Symfony 8.2's messenger.transport.interop_serializer are not recorded in history by default because it strips MonitorStamp on the initial send.
The bundle does not currently provide a stamp header mapper to preserve monitoring metadata.
Disable Monitoring
You may want to disable monitoring for certain messages. There are several ways to do this:
- When dispatching the message, add the
DisableMonitoringStamp:use Zenstruck\Messenger\Monitor\Stamp\DisableMonitoringStamp; /** @var \Symfony\Component\Messenger\MessageBusInterface $bus */ $bus->dispatch(new MyMessage(), [new DisableMonitoringStamp()]);
- Add the
DisableMonitoringStampas a class attribute to your message (or parent class/interface):use Zenstruck\Messenger\Monitor\Stamp\DisableMonitoringStamp; #[DisableMonitoringStamp] class MyMessage { }
You may want to disable monitoring for messages that are dispatched without any handler. You can do this by using theDisableMonitoringStampwith optional constructor argumenttrue:use Zenstruck\Messenger\Monitor\Stamp\DisableMonitoringStamp; #[DisableMonitoringStamp(onlyWhenNoHandler: true)] class MyMessage { }
- Add the message class to the
excludeconfig option (can be abstract/interface):# config/packages/zenstruck_messenger_monitor.yaml zenstruck_messenger_monitor: storage: exclude: - App\Message\MyMessage
- Set
auto_stamp: falseto stop addingMonitorStampwhen dispatching messages. This lets applications without the bundle consume messages that would otherwise carry this stamp.# config/packages/zenstruck_messenger_monitor.yaml zenstruck_messenger_monitor: storage: auto_stamp: false
AddMonitorStampwhen dispatching a message you want to monitor:use Zenstruck\Messenger\Monitor\Stamp\MonitorStamp; /** @var \Symfony\Component\Messenger\MessageBusInterface $bus */ $bus->dispatch(new MyMessage(), [new MonitorStamp()]);
Symfony Scheduler messages are still stamped when the worker receives them.
Store Message Input
Input capture is disabled by default. To store the input of a monitored message, dispatch it with
EnableInputStoreStamp:
use Zenstruck\Messenger\Monitor\Stamp\EnableInputStoreStamp; $bus->dispatch(new MyMessage(), [new EnableInputStoreStamp()]);
You can also add #[EnableInputStoreStamp] to the message class, or set storage.store_input: true
to capture input for all monitored messages.
Input may include sensitive fields or email content. Add DisableInputStoreStamp as a dispatch stamp
or class attribute to exclude a message. It takes precedence over the configuration and enable stamp.
The message details show input normalized by the app's Symfony Serializer. If you disabled
framework.serializer or framework.property_access, enable them to capture ordinary message objects.
use Zenstruck\Messenger\Monitor\Stamp\DisableInputStoreStamp; #[DisableInputStoreStamp] class SensitiveMessage { }
Input is captured when the worker receives the message, before handling it. If normalization fails, input is omitted and the message can still be handled and recorded.
Description
The stored ProcessedMessage has a description property. This is helpful to differentiate between
messages in the user interface. By default, this is the stringified version of the message object
(if it implements \Stringable). You can add the DescriptionStamp to customize:
use Zenstruck\Messenger\Monitor\Stamp\DescriptionStamp; /** @var \Symfony\Component\Messenger\MessageBusInterface $bus */ $bus->dispatch(new MyMessage(), [new DescriptionStamp('some custom description')]);
When Symfony Mailer queues an Email, the bundle automatically uses its subject as the
description and includes the recipient when there is exactly one. A Mailer TagHeader
(X-Tag) is also copied to the message's monitoring tags.
Message Flows
On Symfony 8.2+, enable identity stamps to connect recorded messages in the same flow:
framework: messenger: identity_stamps: true
Message chains still run when identity_stamps is disabled.
Without identity stamps, the bundle records each message separately and hides the Flow section.
Existing retry history remains available.
Message details show related messages in parent-to-child order, with the current message highlighted, parallel branches nested, and retry attempts grouped per message. The list includes recorded history; queued steps and messages whose history has been purged are not reconstructed.
Doctrine storage fetches the list in one query without loading message inputs or handler results. Generate a migration for the three nullable identity columns and their indexes before using this version. Older Symfony versions keep their existing history behavior.
Handler Measurements
On Symfony 8.2+, message details show each handler's duration and memory change alongside its result, using Symfony's per-handler events. Measurements are stored in the existing results JSON column, so no schema migration is needed.
Memory change is the difference in PHP memory usage before and after the handler. It can be negative when memory is freed, and does not capture temporary allocations freed before the handler returns. Measurements are omitted for batch handlers, older Symfony versions, and existing history without them.
Tags
To help with filtering processed messages, they can have one or more tags. Some tags
are added automatically (like schedule if it's a scheduled message) but you can also
add your own in one of two ways:
-
When dispatching the message, add one or more
TagStamp's:use Zenstruck\Messenger\Monitor\Stamp\TagStamp; /** @var \Symfony\Component\Messenger\MessageBusInterface $bus */ $bus->dispatch(new MyMessage(), [new TagStamp('tag-1'), new TagStamp('tag-2')]);
-
Add the
TagStampas a class attribute to your message (and parent class/interface):use Zenstruck\Messenger\Monitor\Stamp\TagStamp; #[TagStamp('tag-1')] #[TagStamp('tag-2')] class MyMessage { }
You can also add the
TagStampattribute to parent classes and interfaces.
Tag filters match a complete tag and its colon-separated descendants. For example, schedule
matches schedule:default:task. Characters such as % and _ are matched literally.
messenger:monitor:purge Command
Use messenger:monitor:purge to control the size of your history table. It deletes history
entries without removing messages from transports. --older-than accepts 1-hour, 1-day,
1-week, 1-month (the default), or all.
bin/console messenger:monitor:purge # by default, purges all messages older than 1 month bin/console messenger:monitor:purge --older-than all bin/console messenger:monitor:purge --older-than 1-day bin/console messenger:monitor:purge --older-than 1-week bin/console messenger:monitor:purge --status failed # purge only failed messages bin/console messenger:monitor:purge --exclude-schedules # ignore messages tagged with "schedule"
The --status option accepts success or failed. Invalid values stop the command before
any history is deleted. Omit the option to purge both statuses.
Limit deletion with --type, --transport, --tag, and --not-tag. Tags can be repeated;
all included tags must match, and any excluded tag prevents deletion.
bin/console messenger:monitor:purge --older-than 1-week --transport async --status success
bin/console messenger:monitor:purge --type 'App\Message\MyMessage' --tag reports --not-tag important
Note
Schedule this command to run daily with symfony/scheduler and
RunCommandMessage.
messenger:monitor:schedule:purge Command
If using symfony/scheduler, you might want to keep a specific number of these messages as they might run
very infrequently. When running messenger:monitor:purge, add the --exclude-schedules option to
avoid deleting schedule history. Then run messenger:monitor:schedule:purge to keep a specific number
(10 by default) of task run histories.
bin/console messenger:monitor:schedule:purge # by default, keeps 10 runs for each task bin/console messenger:monitor:schedule:purge --keep 5 # keep only 5 bin/console messenger:monitor:schedule:purge default maintenance --keep 5 # selected schedules
Use the --remove-orphans option to delete schedule task runs that are no longer associated with a schedule.
bin/console messenger:monitor:schedule:purge --remove-orphans
Note
Schedule this command to run daily with symfony/scheduler and
RunCommandMessage.
User Interface
Note
Storage must be configured for this feature.
Install Twig and Symfony's SecurityBundle if your app does not already use them:
composer require symfony/twig-bundle symfony/security-bundle
Create a controller that extends Zenstruck\Messenger\Monitor\Controller\MessengerMonitorController
in your app:
// src/Controller/MessengerMonitorController.php namespace App\Controller; use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\Security\Http\Attribute\IsGranted; use Zenstruck\Messenger\Monitor\Controller\MessengerMonitorController as BaseMessengerMonitorController; #[Route('/admin/messenger')] // path prefix for the controllers #[IsGranted('ROLE_ADMIN')] // alternatively, use a firewall final class MessengerMonitorController extends BaseMessengerMonitorController { }
You can now access the dashboard at: /admin/messenger or with the route zenstruck_messenger_monitor_dashboard.
The UI includes a dashboard, searchable history, per-message statistics, transport queues,
message details, and schedules when symfony/scheduler is installed. Queue counts require a
transport implementing MessageCountAwareInterface; browsing, retrying, and removing messages
require ListableReceiverInterface.
Warning
It is important that your MessengerMonitorController is only accessible by
site administrators as it contains sensitive application information. Use either the
IsGranted attribute on your controller as shown above and/or ensure the controller is
behind an access-controlled firewall
that only allows site administrators.
Retrying or removing queued messages and manually triggering scheduled tasks require Symfony's CSRF protection. Install the component and enable it in your app. Stateful protection requires sessions and works on all supported Symfony versions.
composer require symfony/security-csrf
# config/packages/framework.yaml framework: csrf_protection: true session: true
On Symfony 7.2+, you can use stateless CSRF protection by adding these action IDs to your app's existing list:
framework: csrf_protection: enabled: true stateless_token_ids: - zenstruck_messenger_monitor_remove - zenstruck_messenger_monitor_retry - zenstruck_messenger_monitor_trigger
Stateless protection does not require sessions. Success notifications appear when sessions are enabled. The UI supports Symfony's double-submit cookie checks.
The dashboard and other read-only views remain available without CSRF protection. Mutation requests throw a configuration error until it is enabled.
Install knplabs/knp-time-bundle (composer require knplabs/knp-time-bundle) to display
friendlier times and durations in the UI. Install lorisleiva/cron-translator
(composer require lorisleiva/cron-translator) to display friendlier cron expressions
for your scheduled tasks.
The default layout loads its CSS and JavaScript from jsDelivr, with no asset build required. Live widgets refresh every five seconds while the tab is visible and have pause/resume controls.
Customizing templates
Override bundle templates under templates/bundles/ZenstruckMessengerMonitorBundle/, keeping
the same relative path as the bundle's templates/ directory. Extend the original
with the @!ZenstruckMessengerMonitor namespace, as in the navigation example below.
Override the layout's stylesheets and javascripts blocks to use your own assets. Keep the
refresh and action controllers when replacing the JavaScript. Live widget content is rendered
from components/ templates on both the initial page and subsequent refreshes.
Custom navigation links
To add links under Application in the sidebar, override navbar_custom_menu in
templates/bundles/ZenstruckMessengerMonitorBundle/layout.html.twig.
{% extends '@!ZenstruckMessengerMonitor/layout.html.twig' %}
{% block navbar_custom_menu %}
<li class="nav-item"><a href="{{ path('app_homepage') }}" class="nav-link">Home</a></li>
{% endblock %}
Advanced Usage
Autowire the following services by their class or interface to build your own dashboards, commands, or health checks. The examples assume the services have been injected into your code.
Workers Service
Zenstruck\Messenger\Monitor\Workers provides a live view of workers through the configured
cache pool. It does not require history storage.
use Zenstruck\Messenger\Monitor\Workers; /** @var Workers $workers */ $running = $workers->isRunning(); $workerCount = count($workers); $asyncWorkers = $workers->forTransport('async'); $queueWorkers = $workers->forQueue('high_priority'); foreach ($workers as $worker) { $status = $worker->status(); $handled = $worker->messagesHandled(); printf("%s: %d messages handled\n", $status, $handled); }
all(), forTransport(), and forQueue() return arrays of WorkerInfo objects. Queue names
reflect workers started with messenger:consume --queues.
WorkerInfo
| Method | Value |
|---|---|
status(), isIdle(), isProcessing() |
Current worker state: idle or processing |
startTime(), runningFor() |
Start time as DateTimeImmutable, uptime in seconds |
transports(), queues() |
Transport and queue names consumed by this worker |
messagesHandled() |
Messages handled since the worker started |
memoryUsage() |
Last reported memory usage as a Zenstruck\Bytes object |
cooldownFor($transport) |
Active TransportCooldown, or null |
On Symfony 8.2+, the dashboard shows each worker's transport cooldowns and the number of workers cooling down per transport. Known resume times expire automatically; cooldowns with no known end remain visible until polling resumes. Other transports can still be consumed. Transport pages show the same worker-count summary for the selected transport. See Symfony's transport cooldown documentation.
Use $worker->cooldownFor('async') to inspect an active cooldown, or
$transport->coolingDownWorkers() to find the affected workers. Older Symfony versions
keep their existing worker monitoring without cooldown indicators.
TransportCooldown::endsAt() returns a DateTimeImmutable, or null when the resume time
is unknown. transport() returns the transport name.
Worker cache
Workers report their state to cache.app by default. The console monitor, web application,
and workers must use the same pool and cache namespace. For workers on separate hosts or in
containers, configure a shared pool, for example Redis:
# config/packages/cache.yaml framework: cache: prefix_seed: my_app pools: cache.messenger_monitor: adapter: cache.adapter.redis provider: '%env(REDIS_URL)%' # config/packages/zenstruck_messenger_monitor.yaml zenstruck_messenger_monitor: cache: pool: cache.messenger_monitor expired_worker_ttl: 3600
Set REDIS_URL to your Redis connection DSN and use a stable prefix_seed unique to your app.
Worker entries expire after expired_worker_ttl seconds without an update. Gracefully stopped workers are removed
immediately; crashed workers remain visible until their entries expire. Set the TTL longer
than your longest message handling time to avoid active workers temporarily disappearing.
Transports Service
Zenstruck\Messenger\Monitor\Transports exposes the configured Messenger receivers without
requiring history storage. Iterate it for TransportInfo objects keyed by transport name,
or use get($name), names(), all(), and count().
use Zenstruck\Messenger\Monitor\Transports; /** @var Transports $transports */ $async = $transports->get('async'); $running = $async->isRunning(); $filter = $transports->filter(); $filter = $filter->countable(); $filter = $filter->excludeSync(); $filter = $filter->excludeSchedules(); foreach ($filter as $name => $transport) { printf("%s: %d queued messages\n", $name, count($transport)); }
Filters return new filter objects and can be combined. Available filters are countable(),
listable(), excludeSync(), excludeSchedules(), and excludeFailed().
Use names() or all() to get the filtered result as an array.
failure() returns the first transport whose name contains fail, or null.
TransportInfo::isFailure() and excludeFailed() use the same naming convention.
TransportInfo
| Method | Value |
|---|---|
name(), get() |
Transport name and underlying TransportInterface |
isCountable(), isListable() |
Whether the transport supports counting or browsing |
count() |
Queued message count; requires MessageCountAwareInterface |
list($limit = null) |
Collection of QueuedMessage objects; requires ListableReceiverInterface |
find($id) |
A QueuedMessage, or null; requires ListableReceiverInterface |
workers(), isRunning() |
Workers consuming this transport and whether any are running |
coolingDownWorkers() |
Workers currently cooling down for this transport |
Check the capabilities before counting, listing, or finding messages. Unsupported operations
throw LogicException. Iterating a TransportInfo is equivalent to iterating its list().
QueuedMessage
Represents a message still in a transport, including a failed transport.
| Method | Value |
|---|---|
id() |
Transport message ID, or null when no ID stamp exists |
envelope() |
Original Messenger Envelope |
message() |
Message type and description |
stamps(), tags() |
Stamp types and monitoring tags |
dispatchedAt() |
Dispatch time, or null without a MonitorStamp |
exception(), exceptionTrace() |
Failure type/message and trace when available |
Schedules Service
Zenstruck\Messenger\Monitor\Schedules is available when symfony/scheduler is installed.
It discovers registered schedule providers automatically. History storage is only required
for the history() methods.
use Zenstruck\Messenger\Monitor\Schedules; /** @var Schedules $schedules */ $schedule = $schedules->get('default'); $running = $schedule->isRunning(); foreach ($schedule as $task) { $trigger = $task->trigger(); $nextRun = $trigger->nextRunDate(); $nextRunLabel = $nextRun?->format('c') ?? 'no upcoming run'; $taskId = $task->id(); printf("%s: %s\n", $taskId, $nextRunLabel); }
Use names() to list schedule names, iterate the service for ScheduleInfo objects, or
count() it. Calling get() without a name selects the first registered schedule.
history($specification = null) returns a snapshot across all scheduled tasks.
ScheduleInfo
Iterate a schedule for its TaskInfo objects, or use task($id) to select one. count()
returns the number of recurring tasks. name() identifies the schedule and get() returns
the underlying Symfony Schedule.
transport() returns the scheduler_<name> transport. workers() and isRunning() report
whether workers are consuming it. Upcoming run dates describe the schedule; a worker must
be consuming the scheduler transport for tasks to execute.
history($specification = null) returns a snapshot restricted to this schedule's tasks.
Pass a Specification or an array of filters to narrow the history further.
TaskInfo
id() identifies the recurring task, schedule() returns its ScheduleInfo, and get()
returns the underlying RecurringMessage. Use messages() for an array of MessageInfo
objects and trigger() for its TriggerInfo.
history($specification = null) returns a snapshot restricted to this task's schedule tag.
Pass a Specification or an array of filters, for example ['period' => 'in-last-week'].
With no filters it includes all retained attempts. Automatically assigned task tags have the
form schedule:<schedule-name>:<task-id>; manually triggered UI runs also carry manual.
MessageInfo
type() returns the type of the message after unwrapping envelopes and
RedispatchMessage wrappers. isRedispatch() identifies a redispatched message and
redispatchTransports() returns its destination transport names. get() returns the
original object, including any wrapper.
TriggerInfo
nextRunDate() returns the next run after the current time, or null if there is none.
isCron() identifies a cron trigger even when it is decorated. get() returns the original
trigger, inner() the undecorated trigger, and decorators() its decorators.
type(), innerType(), and decoratorTypes() provide their type information.
History
Note
Storage must be configured for this feature.
Storage Service
Autowire Zenstruck\Messenger\Monitor\History\Storage to access processed message history.
The bundle registers its Doctrine implementation when storage.orm.entity_class is configured.
use Zenstruck\Messenger\Monitor\History\Specification; use Zenstruck\Messenger\Monitor\History\Storage; /** @var Storage $storage */ $specification = Specification::create([ 'period' => 'in-last-week', 'transport' => 'async', 'status' => Specification::FAILED, ]); $messages = $storage->filter($specification); $total = count($messages); $latest = $messages->first(); // ProcessedMessage or null $page = $messages->paginate(page: 1, limit: 20); foreach ($page as $message) { $finishedAt = $message->finishedAt(); $description = $message->description(); printf("%s: %s\n", $finishedAt->format('c'), $description); }
filter() returns a Zenstruck\Collection supporting iteration, first(), take(), and
paginate(). Doctrine applies limits and pagination in the database.
find($id) returns a ProcessedMessage or null.
delete($id) removes one history entry. purge($specification) removes matching history
entries and returns the number deleted. Neither operation changes queued messages.
Specification
Zenstruck\Messenger\Monitor\History\Specification describes history filters. new()
creates an unrestricted specification, sorted by finish time descending.
create() accepts an array, a Period enum, a period string, or an existing specification.
| Array key | Accepted value |
|---|---|
period |
A Period enum or period string; replaces from and to |
from, to |
DateTimeImmutable, date string, or null; inclusive bounds on finish time |
status |
Specification::SUCCESS, Specification::FAILED, or null for both |
message_type |
Fully qualified message class name |
transport |
Transport name |
tags, not_tags |
A tag string or array of tags to include or exclude |
run_id |
Monitoring run ID, shared by retry attempts |
search |
Text to search in descriptions, tags, failure messages, stored input, and handler output |
sort |
Specification::ASC or Specification::DESC |
Filters combine with AND. Every included tag must match; any excluded tag prevents a match.
Tags match their colon-separated descendants as described under Tags. Search is
case-insensitive and treats % and _ literally.
The fluent methods return a new specification, leaving the original unchanged:
use Zenstruck\Messenger\Monitor\History\Specification; $specification = Specification::new(); $specification = $specification->from('-7 days'); $specification = $specification->on('async'); $specification = $specification->failures(); $specification = $specification->with('reports'); $specification = $specification->without('manual');
Other fluent filters are to($date), for($messageClass), successes(), sortAscending(),
and sortDescending(). with() and without() each accept multiple tags and replace their
previous tag list. Use toArray() to inspect the resulting filters.
Snapshot
Create a Zenstruck\Messenger\Monitor\History\Snapshot from a specification and storage:
use Zenstruck\Messenger\Monitor\History\Period; use Zenstruck\Messenger\Monitor\History\Specification; use Zenstruck\Messenger\Monitor\History\Storage; /** @var Storage $storage */ $specification = Specification::create(Period::IN_LAST_DAY); $snapshot = $specification->snapshot($storage); $total = $snapshot->totalCount(); $failed = $snapshot->failureCount(); $failurePercentage = $snapshot->failRate() * 100; $averageHandlingMilliseconds = $snapshot->averageHandlingTime(); $messagesPerHour = $snapshot->handledPerHour();
| Method | Value |
|---|---|
totalCount(), successCount(), failureCount() |
Attempt counts, including retries as separate attempts |
failRate() |
Failed attempts divided by total attempts, from 0 to 1 |
averageWaitTime(), averageHandlingTime(), averageProcessingTime() |
Average durations in milliseconds |
handledPerMinute(), handledPerHour(), handledPerDay() |
Average throughput over the specification's time range |
messages() |
Matching history collection |
perMessageTypeMetrics() |
Collection of metrics grouped by message class |
Counts include both statuses even when the specification filters by status. That status
filter applies to messages() and the average durations. Empty counts, failure rates, and
average durations are zero. With no from date, throughput uses the oldest retained history
entry as its starting point. Prefer an explicit period for reporting.
Snapshot counts and averages are loaded once per instance. Create a new snapshot for fresh
metrics. Per-message-type metrics expose type(), total and failure counts, average durations,
failure rate, and throughput. They ignore the specification's message-type filter so you can
compare classes; the other filters still apply.
ProcessedMessage and handler results
Each ProcessedMessage represents one processing attempt. id() is the history entry's ID,
runId() groups retry attempts, and attempt() starts at 1. Use a specification with run_id
to fetch the other attempts.
type(), description(), transport(), and tags() describe the message. input() returns
its captured input or null. dispatchedAt(), receivedAt(), and finishedAt() return
DateTimeImmutable values. timeInQueue(), timeToHandle(), and timeToProcess() are in
milliseconds; memoryUsage() returns a Zenstruck\Bytes object.
isFailure() identifies a failed attempt and failure() returns its exception type and
message, or null. Iterate results() for individual handler results, or select
successes() and failures(). Each result exposes handler(), data(), isFailure(),
and failure(). On supported Symfony versions, duration() returns milliseconds and
memoryChange() returns a signed byte count; both are nullable. See Handler Measurements.
On Symfony 8.2+, messageId(), correlationId(), and causationId() expose the optional
message flow identities.
Type
Zenstruck\Messenger\Monitor\Type describes a message, handler, stamp, trigger, or exception.
Use class() for its fully qualified class name, shortName() for the name without its
namespace, and description() for an optional human-readable description.
object() returns the wrapped object when available. History types contain class names
without reconstructing the original objects.
Others
Hide Log-Entries
While running bin/console messenger:consume async -vv, you may see cache log entries such as:
[cache] Lock acquired, now computing item "zenstruck_messenger_monitor.worker.xxx" ["key" => "zenstruck_messenger_monitor.worker.xxx"]
Exclude the cache channel from your console handler in config/packages/monolog.yaml:
when@dev: monolog: handlers: console: # ... channels: ['!event', '!doctrine', '!console', '!cache']
Full Default Bundle Configuration
Storage is disabled until storage.orm.entity_class is set. These are the available options
and their defaults:
zenstruck_messenger_monitor: storage: # Whether to add a MonitorStamp when dispatching messages to a transport. auto_stamp: true # Whether to store message input in history by default. store_input: false # Message classes to disable monitoring for (can be abstract/interface) exclude: [] orm: # Set a subclass of "Zenstruck\Messenger\Monitor\History\Model\ProcessedMessage" to enable storage. # entity_class: App\Entity\ProcessedMessage # Doctrine entity manager to use. entity_manager: default cache: # Cache pool used by both workers and the monitor. Share it across hosts/containers. pool: cache.app # Seconds without an update before a worker entry expires. expired_worker_ttl: 3600



