Dbal Dead Letter

DBAL-based dead letter queue for storing and replaying failed messages

You want failed messages stored next to your application data so they survive a broker restart, can be queried with SQL, and replayed via a console command without writing custom tooling. The Dbal Dead Letter is a table in the same database your aggregates live in, holding every error message with its exception, headers, and payload — ready to be reviewed, replayed, or deleted.

Dbal Dead Letter

Ecotone provides full lifecycle management of error messages via the 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

To make use of Dead Letter, we need to have Ecotone's Dbal Module installed.

Storing Messages in Dead Letter

If we configure default error channel to point to "dbal_dead_letter" then all Error Messages will land there directly

Storing Error Messages once they failed directly in Database

Symfony

config/packages/ecotone.yaml

ecotone:
  defaultErrorChannel: "dbal_dead_letter"

Laravel

config/ecotone.php

return [
    'defaultErrorChannel' => 'dbal_dead_letter',
];

Lite

$ecotone = EcotoneLite::bootstrap(
    configuration: ServiceConfiguration::createWithDefaults()
        ->withDefaultErrorChannel('dbal_dead_letter')
);

Dead Letter with Delayed Retries

We may also want to try to recover before we consider Message to be stored in Dead Letter:

Storing Error Messages in Dead Letter only if retries are exhausted

Symfony

config/packages/ecotone.yaml

ecotone:
  defaultErrorChannel: "errorChannel"

Laravel

config/ecotone.php

return [
    'defaultErrorChannel' => 'errorChannel',
];

Lite

$ecotone = EcotoneLite::bootstrap(
    configuration: ServiceConfiguration::createWithDefaults()
        ->withDefaultErrorChannel('errorChannel')
);

and then we use inbuilt Retry Strategy:

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

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.