Skip to content

Provided a better solution for reading dead outbox entries #1940

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 46 additions & 18 deletions java/outbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -355,29 +355,58 @@ It is crucial to make the service `OutboxDeadLetterQueueService` accessible for

:::

### Filter for Dead Entries
### Reading Dead Entries

This filtering can't be done on the database since the maximum number of attempts is only available from the CDS properties.

To ensure that only dead outbox entries are returned when reading `DeadOutboxMessages`, the following code provides the handler for the `DeadLetterQueueService` and the `@After-READ` handler that filters for the dead outbox entries:
Filtering the dead entries is done by adding by adding an appropriate `where`-clause to `READ`-queries on the outbox message entries which reached maximum number of retries. The following code provides an example handler implementation defining this behaviour for the `DeadLetterQueueService`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Filtering the dead entries is done by adding by adding an appropriate `where`-clause to `READ`-queries on the outbox message entries which reached maximum number of retries. The following code provides an example handler implementation defining this behaviour for the `DeadLetterQueueService`:
Filtering the dead entries is done by adding an appropriate `where`-clause to all `READ`-queries which covers all outbox message entries with maximum number of retries. The following code provides an example handler implementation defining this behaviour for the `DeadLetterQueueService`:


```java
@Component
@ServiceName(OutboxDeadLetterQueueService_.CDS_NAME)
public class DeadOutboxMessagesHandler implements EventHandler {

@After(entity = DeadOutboxMessages_.CDS_NAME)
public void filterDeadEntries(CdsReadEventContext context) {
CdsProperties.Outbox outboxConfigs = context.getCdsRuntime().getEnvironment().getCdsProperties().getOutbox();
List<DeadOutboxMessages> deadEntries = context
.getResult()
.listOf(DeadOutboxMessages.class)
.stream()
.filter(entry -> entry.getAttempts() >= outboxConfigs.getService(entry.getTarget()).getMaxAttempts())
.toList();

context.setResult(deadEntries);
}
private final PersistenceService db;

public DeadOutboxMessagesHandler(@Qualifier(PersistenceService.DEFAULT_NAME) PersistenceService db) {
this.db = db;
}

@Before(entity = DeadOutboxMessages_.CDS_NAME)
public void addDeadEntryFilter(CdsReadEventContext context) {
Optional<Predicate> outboxFilters = this.createOutboxFilters(context.getCdsRuntime());

if (outboxFilters.isPresent()) {
CqnSelect modifiedCqn =
copy(
context.getCqn(),
new Modifier() {
@Override
public CqnPredicate where(Predicate where) {
return outboxFilters.get().and(where);
}
});
context.setCqn(modifiedCqn);
}
}

private Optional<Predicate> createOutboxFilters(CdsRuntime runtime) {
List<OutboxService> outboxServices = runtime.getServiceCatalog().getServices(OutboxService.class)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what about iterating the persistent outboxes from application configuration (outboxConfigs)+ the known defaults? INMEMORY_NAME would not be required.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BraunMatthias If an outbox has the default configuration, iterating over the configurations doesn't return the specific config for an outbox. I observed this while testing the code; in this case no outbox can be found and hence no dead entries are read at all.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be only true for the two default outboxes which needed to be explicitly named here. But what happens in 398 for those?

.filter(s -> !s.getName().equals(OutboxService.INMEMORY_NAME)).toList();
CdsProperties.Outbox outboxConfigs = runtime.getEnvironment().getCdsProperties().getOutbox();

Predicate where = null;
for(OutboxService service : outboxServices) {
OutboxServiceConfig config = outboxConfigs.getService(service.getName());
Predicate targetPredicate = CQL.get(Messages.TARGET).eq(service.getName()).and(CQL.get(Messages.ATTEMPTS).ge(config.getMaxAttempts()));
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why do we need to filter by individual outbox and then OR the condition meeting all outboxes?

Copy link
Contributor Author

@t-bonk t-bonk Jul 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BraunMatthias Every outbox can have its own configuration for maxAttempts. To read only the dead entries per outbox, this filter is required.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same reason - I just overlooked this aspect


if (where == null) {
where = targetPredicate;
} else {
where = where.or(targetPredicate);
}
}

return Optional.ofNullable(where);
}
}
```

Expand Down Expand Up @@ -419,8 +448,7 @@ The injected `PersistenceService` instance is used to perform the operations on
[Learn more about CQL statement inspection.](./working-with-cql/query-introspection#cqnanalyzer){.learn-more}

::: tip Use paging logic
Avoid to read all entries of the `cds.outbox.Messages` or `OutboxDeadLetterQueueService.DeadOutboxMessages` table at once, as the size of an entry is unpredictable
and depends on the size of the payload. Prefer paging logic instead.
Avoid to read all outbox entries at once as a single entry can have significant size reflecting the request's payload. Prefer `READ`-queries with paging instead.
:::

## Observability using Open Telemetry
Expand Down