|
| 1 | +# Error Channel and Dead Letter |
| 2 | + |
| 3 | +## Error Channel |
| 4 | + |
| 5 | +`Ecotone` comes with solution called Error Channel. \ |
| 6 | +Error Channel is a place where unrecoverable Errors can go, this way we can preserve Error Messages even if we can't handle anyhow. \ |
| 7 | +Error Channel may log those Messages, store them in database, push them to some Asynchronous Channel. The what is to be done is flexibile and can be adjusted to Application needs. |
| 8 | + |
| 9 | +## Configuration |
| 10 | + |
| 11 | +Error Channel can be configured per Message Consumer, or globally as default Error Channel for all Message Consumers: |
| 12 | + |
| 13 | +* [Set up default error channel for all consumers](../../../../messaging/service-application-configuration.md#ecotone-core-configuration) |
| 14 | + |
| 15 | +  \- [Symfony](../../../../modules/symfony/symfony-ddd-cqrs-event-sourcing.md#defaulterrorchannel) |
| 16 | + |
| 17 | +  \- [Laravel](../../../../modules/laravel/laravel-ddd-cqrs-event-sourcing.md#defaulterrorchannel) |
| 18 | + |
| 19 | +  \- [Lite](../../../../modules/ecotone-lite/#withdefaulterrorchannel) |
| 20 | + |
| 21 | +{% tabs %} |
| 22 | +{% tab title="Symfony" %} |
| 23 | +**config/packages/ecotone.yaml** |
| 24 | + |
| 25 | +```yaml |
| 26 | +ecotone: |
| 27 | + defaultErrorChannel: "errorChannel" |
| 28 | +``` |
| 29 | +{% endtab %} |
| 30 | +
|
| 31 | +{% tab title="Laravel" %} |
| 32 | +**config/ecotone.php** |
| 33 | +
|
| 34 | +```php |
| 35 | +return [ |
| 36 | + 'defaultErrorChannel' => 'errorChannel', |
| 37 | +]; |
| 38 | +``` |
| 39 | +{% endtab %} |
| 40 | + |
| 41 | +{% tab title="Lite" %} |
| 42 | +```php |
| 43 | +$ecotone = EcotoneLite::bootstrap( |
| 44 | + configuration: ServiceConfiguration::createWithDefaults() |
| 45 | + ->withDefaultErrorChannel('errorChannel') |
| 46 | +); |
| 47 | +``` |
| 48 | +{% endtab %} |
| 49 | +{% endtabs %} |
| 50 | + |
| 51 | +* [Set up for specific consumer](../../../asynchronous-handling/#static-configuration) |
| 52 | + |
| 53 | +```php |
| 54 | +class Configuration |
| 55 | +{ |
| 56 | + #[ServiceContext] |
| 57 | + public function configuration() : array |
| 58 | + { |
| 59 | + return [ |
| 60 | + // For Message Consumer orders, configure error channel |
| 61 | + PollingMetadata::create("orders") |
| 62 | + ->setErrorChannelName("errorChannel") |
| 63 | + ]; |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +{% hint style="info" %} |
| 69 | +Setting up Error Channel means that [Message Consumer](../../../../messaging/contributing-to-ecotone/demo-integration-with-sqs/message-consumer-and-publisher.md#message-consumer) will send Error Message to error channel and then continue handling next messages.\ |
| 70 | +\ |
| 71 | +After sending Error Message to Error Channel, message is considered handled as long as Error Handler does not throw exception. |
| 72 | +{% endhint %} |
| 73 | + |
| 74 | +## Manual Handling |
| 75 | + |
| 76 | +To handle incoming Error Messages, we can bind to our defined Error Channel using [ServiceActivator](../../../../messaging/messaging-concepts/): |
| 77 | + |
| 78 | +```php |
| 79 | +#[ServiceActivator("errorChannel")] |
| 80 | +public function handle(ErrorMessage $errorMessage): void |
| 81 | +{ |
| 82 | + // do something with ErrorMessage |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +{% hint style="info" %} |
| 87 | +Service Activator are endpoints like Command Handlers, however they are not exposed using Command/Event/Query Buses. \ |
| 88 | +You may use them for internal handling. |
| 89 | +{% endhint %} |
| 90 | + |
| 91 | +## Delayed Retries |
| 92 | + |
| 93 | +We can also use inbuilt retry mechanism, that will be resend Error Message to it's original Message Channel with delay. If our Default Error Channel is configured for name **"errorChannel"**, then we can connect it like bellow: |
| 94 | + |
| 95 | +```php |
| 96 | +#[ServiceContext] |
| 97 | +public function errorConfiguration() |
| 98 | +{ |
| 99 | + return ErrorHandlerConfiguration::create( |
| 100 | + "errorChannel", |
| 101 | + RetryTemplateBuilder::exponentialBackoff(1000, 10) |
| 102 | + ->maxRetryAttempts(3) |
| 103 | + ); |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +## Discarding all Error Messages |
| 108 | + |
| 109 | +If for some cases we want to discard Error Messages, we can set up error channel to default inbuilt one called **"nullChannel"**. \ |
| 110 | +That may be used in combination of retries, if after given attempt Message is still not handled, then discard: |
| 111 | + |
| 112 | +```php |
| 113 | +#[ServiceContext] |
| 114 | +public function errorConfiguration() |
| 115 | +{ |
| 116 | + return ErrorHandlerConfiguration::createWithDeadLetterChannel( |
| 117 | + "errorChannel", |
| 118 | + RetryTemplateBuilder::exponentialBackoff(1000, 10) |
| 119 | + ->maxRetryAttempts(3), |
| 120 | + // if retry strategy will not recover, then discard |
| 121 | + "nullChannel" |
| 122 | + ); |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +## Dbal Dead Letter |
| 127 | + |
| 128 | +Ecotone comes with full support for managing full life cycle of a error message. Read more in next [section](dbal-dead-letter.md). |
0 commit comments