Messenger Inspector

The Interface

The list starts with messages that need attention: failed, retrying and stale messages. Change the status filter to see other messages, or search by class, description, error message or transport. The date filter narrows the results further. Turn on auto-refresh to follow changes as they happen.

Click a message to open its details, including attempts, timings, errors and captured payload. The interface labels sent messages as Queued and handled messages as Succeeded.

For failed messages, you can:

• Retry: send the message through the bus again. Its row returns to pending and follows the message lifecycle again.
• Remove: discard it from the failure transport. Its row remains in the inspector as removed until cleanup, even if the envelope was already missing from the transport.

Securing the Admin Actions

Retry and remove both require ROLE_ADMIN by default. Users who can open the inspector without that role can browse messages, but can't use those actions. Protect read access through your controller or Symfony Security configuration as shown above; action permissions don't restrict who can view the page.

Configure the permission of each action separately. This grants retry to your operators and keeps remove for administrators:

1
2
3
4
5
6

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    messenger_inspector:
        actions:
            retry_permission: ROLE_MESSENGER_OPERATOR
            remove_permission: ROLE_ADMIN

Each value is checked with Symfony's isGranted(), so you can use roles (with role hierarchy) or attributes supported by your voters. Setting a permission to null lets every user who can open the inspector perform that action.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

namespace App\Security\Voter;

use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

final class RetryMessageVoter extends Voter
{
    protected function supports(string $attribute, mixed $subject): bool
    {
        return 'RETRY_MESSAGE' === $attribute;
    }

    protected function voteOnAttribute(
        string $attribute,
        mixed $subject,
        TokenInterface $token,
    ): bool {
        if (!\is_array($subject)) {
            return false;
        }

        return 'billing' !== $subject['transport_name'];
    }
}

1
2
3
4
5

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    messenger_inspector:
        actions:
            retry_permission: RETRY_MESSAGE

1
2
3
4
5
6
7
8

use EasyCorp\Bundle\EasyAdminProBundle\MessengerInspector\Option\MessageAction;

protected function denyUnlessActionAllowed(
    MessageAction $action,
    string $messageId,
): void {
    $this->denyAccessUnlessGranted('MANAGE_MESSAGE', $messageId);
}

View Options

Use these methods on the MessengerInspector object returned by configureMessengerInspector() to customize the message list and detail panel:

setPageSize(int $pageSize)

Number of messages per page. Must be a positive integer. Defaults to 30.

displayStackTrace(bool $display = true)

Show captured stack traces in the detail panel. Enabled by default; pass false to hide them. To capture traces, enable capture.error_trace (see Storing Payloads).

enableAutoRefresh(bool $enabled = true)

Start with auto-refresh turned on. Disabled by default. Users can still turn it on or off with the toggle above the list.

setAutoRefreshInterval(int $seconds)

Number of seconds between automatic refreshes. Defaults to 5 and must be at least 1. Setting the interval doesn't turn auto-refresh on.

displayMessagePayload()

Show public message properties in the detail panel (the default). Private, protected and sensitive properties are hidden.

displayFullMessagePayload()

Show all captured properties, including private and protected ones. Sensitive values remain redacted.

hideMessagePayload()

Hide the payload from the detail panel. This doesn't stop capture or remove payloads already stored.

Payload display requires capture.payload to be enabled when the message is recorded (see Storing Payloads). Values of promoted constructor parameters marked with #[\SensitiveParameter] are redacted during capture, so even full display can't reveal them.

By Attribute

Add the DisableInspectionStamp PHP attribute to a message class to exclude every instance of that class. This is the recommended approach for messages that you control:

1
2
3
4
5
6
7
8

namespace App\Message;

use EasyCorp\Bundle\EasyAdminProBundle\MessengerInspector\Stamp\DisableInspectionStamp;

#[DisableInspectionStamp]
final class HeartbeatMessage
{
}

By Stamp

The same class is also a Messenger stamp. Attach it to a single envelope when you want to exclude one specific dispatch:

1
2
3
4
5
6
7
8
9
10
11

use App\Message\ProcessReportMessage;
use EasyCorp\Bundle\EasyAdminProBundle\MessengerInspector\Stamp\DisableInspectionStamp;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\MessageBusInterface;

public function dispatch(MessageBusInterface $bus): void
{
    $bus->dispatch(new Envelope(new ProcessReportMessage(), [
        new DisableInspectionStamp(),
    ]));
}

You can also pass onlyWhenNoHandler: true to keep the message inspected when a handler exists, and skip it only when Messenger does not find any handler. This is useful for messages that are dispatched optimistically.

By Configuration

The included_messages and excluded_messages options take a list of message FQCNs, interfaces or parent classes. included_messages defaults to '*', meaning every message is eligible unless it is explicitly excluded. An exclusion always wins over an inclusion:

1
2
3
4
5
6
7
8
9

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    messenger_inspector:
        included_messages:
            # Only inspect messages of these types or that
            # implement these interfaces.
            - App\Message\Contract\BillingMessage
        excluded_messages:
            - App\Message\InternalDebugMessage

By Sampling

For very high-volume applications, set a fractional sampling rate to keep only a slice of the traffic. Sampling is deterministic per message id, so a given message is either fully tracked across its lifecycle or skipped entirely:

1
2
3
4
5
6

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    messenger_inspector:
        sampling:
            # Keep 10% of messages.
            rate: 0.1

Auto-Stamping

Mailer and Notifier messages get descriptions and tags automatically when those optional components are installed:

• Mailer messages use the mailer tag and a description based on the subject and first recipient.
• Notifier messages use the notifier tag and the message subject.

Your own descriptions take precedence, and existing tags aren't duplicated.

Disable either integration if you don't need it:

1
2
3
4
5
6

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    messenger_inspector:
        auto_stamp:
            mailer: true
            notifier: false

Pruning Old Records

Schedule easyadmin:messenger-inspector:prune to keep the history from growing indefinitely, for example once a night with cron:

1
2
3
4
5
6
7
8
9
10
11

# Preview the cleanup.
$ php bin/console easyadmin:messenger-inspector:prune --dry-run

# Apply the configured retention periods.
$ php bin/console easyadmin:messenger-inspector:prune

# Prune only handled messages.
$ php bin/console easyadmin:messenger-inspector:prune --status=handled

# Use a different retention period for this run.
$ php bin/console easyadmin:messenger-inspector:prune --older-than="30 days"

The default retention periods are 7 days for handled messages, 30 days for failed messages (including removed, retrying and stale), and 2 days for sent or pending messages. Set a period to 0 to disable pruning for those statuses. See Configuration Reference.

The command also marks messages left in processing longer than stale_processing_minutes as stale, and cleans up the optional events table. Use --skip-stale or --skip-events to skip those steps.

To clear all inspector history, use --all. It asks for confirmation; add --force for a non-interactive run. You can preview it with --dry-run or keep event history with --skip-events, but you can't combine --all with --status or --older-than. This deletes inspector records, not messages from your Messenger transports.

Console Stats

The easyadmin:messenger-inspector:stats command prints aggregated statistics from the inspector table to the console:

1
2
3
4
5
6
7
8
9
10
11
12
13

# Stats for the last 24 hours.
$ php bin/console easyadmin:messenger-inspector:stats

# Stats for an explicit time window.
$ php bin/console easyadmin:messenger-inspector:stats \
    --from="2026-04-01T00:00:00Z" \
    --to="2026-04-30T23:59:59Z"

# Limit to transports whose name contains "async" (case-insensitive)
# and show the top 50 message classes and transports.
$ php bin/console easyadmin:messenger-inspector:stats \
    --transport=async \
    --top=50

The output aggregates the data stored by the module: counts per status, summary (success, failure, fail rate, average wait time, average handle time), top message classes and top transports.