Error Channel and Dead Letter

Error Channel

Ecotone comes with solution that allow to push Error Messages to error channel. Depending on what subscribing to error channel you may provide different behaviour. From logging, storing or even discarding the message.

Error Channel

The error channel is channel defined for handling failed messages. As a default it's turned off. We may set up error channel for specific consumer

• Set up default error channel for all consumers

- Symfony

- Laravel

- Lite

• Set up for specific consumer

Setting up Error Channel means that Message Consumer will send Error Message to error channel and then continue handling next messages. After sending Error Message to error channel, message is considered handled.

Manually Handling Error Messages from Error Channel

After setting it up default error channel to "errorChannel" we may subscribe to the errors by setting up ServiceActivator:

#[ServiceActivator("errorChannel")]
public function handle(ErrorMessage $errorMessage): void
{
    // do something with ErrorMessage
}

Service Activator are endpoints like Command Handlers, however they are not exposed using Command/Event/Query Buses. You may use them for internal handling.

Dbal Dead Letter

Ecotone comes with full support for managing full life cycle of a error message by using Dbal Module.

• Store failed Message with all details about the exception

• Allow for reviewing error Messages

• Allow for deleting and replaying error Message back to the Asynchronous Message Channels

Installation

• Install Ecotone's Dbal Module.
• Set up Error Channel like discussed at the beginning of the section
• Set up "errorChannel" in ErrorHandlerConfiguration to "dbal_dead_letter"

#[ServiceContext]
public function errorConfiguration()
{
    return ErrorHandlerConfiguration::createWithDeadLetterChannel(
        "errorChannel",
        //  retry strategy
        RetryTemplateBuilder::exponentialBackoff(1000, 10)
            ->maxRetryAttempts(3),
        // if retry strategy will not recover, then send here
        "dbal_dead_letter"
    );
}

If you would set up "nullChannel" in place of "dbal_dead_letter", then all Message that can't be retried with success would be discared.

Dead Letter Console Commands

Help

Get more details about existing commands

Symfony

bin/console ecotone:deadletter:help

Laravel

artisan ecotone:deadletter:help

Listing Error Messages

Listing current error messages

Symfony

bin/console ecotone:deadletter:list

Laravel

artisan ecotone:deadletter:list

Lite

$list = $messagingSystem->runConsoleCommand("ecotone:deadletter:list", []);

Show Details About Error Message

Get more details about given error message

Symfony

bin/console ecotone:deadletter:show {messageId}

Laravel

artisan ecotone:deadletter:show {messageId}

Lite

$details = $messagingSystem->runConsoleCommand("ecotone:deadletter:show", ["messageId" => $messageId]);

Replay Error Message

Replay error message. It will return to previous channel for consumer to pick it up and handle again.

Symfony

bin/console ecotone:deadletter:replay {messageId}

Laravel

artisan ecotone:deadletter:replay {messageId}

Lite

$messagingSystem->runConsoleCommand("ecotone:deadletter:replay", ["messageId" => $messageId]);

Replay All Messages

Replaying all the error messages.

Symfony

bin/console ecotone:deadletter:replayAll

Laravel

artisan ecotone:deadletter:replayAll

Lite

$messagingSystem->runConsoleCommand("ecotone:deadletter:replayAll", []);

Delete Message

Delete given error message

Symfony

bin/console ecotone:deadletter:delete {messageId}

Laravel

artisan ecotone:deadletter:delete {messageId}

Lite

$messagingSystem->runConsoleCommand("ecotone:deadletter:delete", ["messageId" => $messageId]);

Turn off Dbal Dead Letter

#[ServiceContext]
public function dbalConfiguration()
{
    return DbalConfiguration::createWithDefaults()
        ->withDeadLetter(false);
}

Managing Multiple Ecotone Applications

The above solution requires running Console Line Commands. If we want however, we can manage all our Error Messages from one place using Ecotone Pulse.

This is especially useful when we've multiple Applications, so we can go to single place and see if any Application have failed to process Message.