Symfony Messenger in der Praxis: Backpressure, Poison-Pill-Handling und Rate-Limiting-Muster, die deine Datenbank retten

Das Setup ist vertraut. Du verdrahtest Symfony Messenger für asynchrone Verarbeitung - Webhook-Empfänger, E-Mail-Versand, Hintergrund-Sync-Jobs - und in der Entwicklung funktioniert alles genau wie beschrieben. Dann gehst du in Produktion, ein Zahlungsanbieter schickt innerhalb von fünf Minuten einen Burst von 8.000 Webhook-Events, und dein Monitoring zeigt: Datenbankverbindungen erschöpft, Worker-Prozesse in Fehler-Schleifen, und eine Alert-Queue, die Stunden brauchen wird, um sich zu leeren.

Was ist passiert? Eine langsame externe API hat einen scheinbar unkomplizierten Message-Handler in einen Backpressure-Verstärker verwandelt. Retry-Logik, die für gelegentliche Fehler ausgelegt war, hat den Connection-Pool bei hoher Last gesättigt. Ein einziges fehlerhaftes Event - genau die Art, die dein Schema-Validator nie vorhergesehen hat - wurde tausende Male wiederholt, während legitime Nachrichten dahinter aufgestaut wurden.

Das sind keine Randfälle. Das sind die vorhersehbaren Fehlermodi von Messenger-Deployments, die noch nicht für den Produktionsbetrieb gehärtet wurden. Die folgenden Muster aus der Praxis installieren wir in Client-Systemen, die mehr als 1 Million Nachrichten pro Tag verarbeiten. Backpressure, Poison-Pill-Handling und das passende Rate-Limiting-Muster sind das, was in einem Szenario wie oben deine Datenbank retten kann.

Das Kernproblem: Retry-Amplifikation und Transport-Backpressure

Symfony Messengers Standard-Retry-Konfiguration ist großzügig: drei Versuche mit einem Multiplikator von zwei, beginnend bei einer Sekunde. Für Systeme, die Dutzende Nachrichten pro Minute verarbeiten, ist das in Ordnung. Für Systeme unter anhaltender Last mit einer langsamen Abhängigkeit - eine externe API mit 400ms durchschnittlicher Latenz, ein Doctrine-Listener, der bei jeder verarbeiteten Nachricht eine sekundäre Abfrage abfeuert - glätten Retries die Last nicht, sie verstärken sie.

Der kumulative Effekt ist ein Muster, das wir Retry-Amplifikation nennen: Eine fehlerhafte Nachricht löst drei Retry-Zyklen aus, jeder Retry belegt einen Worker-Prozess für die gesamte Retry-Verzögerung, und währenddessen ziehen andere Worker weiterhin neue Nachrichten. Bei hohen Eingangsraten kann der Worker-Pool gesättigt sein, bevor der Dead-Letter-Schwellenwert je erreicht wird.

Die Lösung hat zwei Teile: Rate Limiting auf Transport-Ebene, damit sich Worker basierend auf dem Zustand der Abhängigkeiten selbst drosseln, und schnelles Failure-Routing, das fehlerhafte Nachrichten aus der Hauptqueue entfernt, bevor sie das Retry-Budget aufbrauchen.

Per-Transport-Rate-Limiting mit Exponential Backoff und Jitter

Symfony Messenger liefert keinen eingebauten Transport-Rate-Limiter, aber die RateLimiterFactory aus der symfony/rate-limiter-Komponente lässt sich sauber über einen benutzerdefinierten Middleware-Wrapper integrieren - genauer gesagt über eine Middleware, die Message-Stamps vor dem Dispatch inspiziert.

Das Muster, das in Produktion gut funktioniert, ist ein Handler-Level-Rate-Limiter, der den aktuellen Worker-Prozess blockiert, anstatt die Nachricht erneut in die Queue zu stellen:

final class RateLimitedHandlerMiddleware implements MiddlewareInterface
{
    public function __construct(
        private readonly RateLimiterFactory $externalApiLimiter,
        private readonly LoggerInterface $logger,
    ) {}

    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        if ($envelope->getMessage() instanceof ExternalApiMessage) {
            $limiter = $this->externalApiLimiter->create('global');
            
            if (!$limiter->consume(1)->isAccepted()) {
                // Diesen Worker blockieren, bis ein Token verfuegbar ist
                $limiter->reserve(1)->wait();
                $this->logger->debug('Rate Limit angewendet, Worker pausiert');
            }
        }

        return $stack->next()->handle($envelope, $stack);
    }
}

Den Rate-Limiter in config/packages/rate_limiter.yaml registrieren:

framework:
    rate_limiter:
        external_api:
            policy: token_bucket
            limit: 100
            rate: { interval: '1 minute', amount: 100 }

Das begrenzt einen bestimmten Transport auf 100 Nachrichten pro Minute, unabhängig davon, wie viele Worker-Prozesse laufen. In Kombination mit der Worker-Anzahl in Supervisor kannst du die SLA deiner externen API direkt in der Konfiguration ausdrücken, anstatt zu hoffen, dass der Downstream jeden Burst übersteht.

Für Exponential Backoff mit Jitter - entscheidend, wenn der Downstream sich von einem Ausfall erholt und du einen Thundering Herd beim Wiederverbinden vermeiden möchtest - überschreibe die Standard-Retry-Strategie pro Transport:

framework:
    messenger:
        transports:
            external_api:
                dsn: '%env(REDIS_DSN)%'
                retry_strategy:
                    max_retries: 5
                    delay: 1000
                    multiplier: 2
                    max_delay: 60000
                    jitter: 0.2

jitter: 0.2 fügt jedem Retry-Delay-Intervall bis zu 20% zufällige Varianz hinzu. Mit einem Multiplikator von 2 beginnend bei einer Sekunde fallen Retry-Slots bei etwa 1s, 2s, 4s, 8s und 16s - mit genügend Streuung, dass hundert gleichzeitig wiederholende Worker nicht alle zur gleichen Zeit auf den wiederhergestellten Service einprallen.

Dead-Letter-Queues mit strukturierter Retry-Klassifizierung

Das Standard-Messenger-Dead-Letter-Setup leitet alle fehlgeschlagenen Nachrichten an einen einzigen failed-Transport weiter, was eine flache Queue erzeugt, in der ein Schema-Validierungsfehler neben einem Netzwerk-Timeout und einer Business-Logic-Exception sitzt - drei Probleme mit völlig unterschiedlichen Recovery-Pfaden.

Das Muster, das wir installieren, ist ein mehrstufiges Dead-Letter-System, das durch den Exception-Typ gesteuert wird:

final class ClassifiedFailureHandler implements MiddlewareInterface
{
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        try {
            return $stack->next()->handle($envelope, $stack);
        } catch (TransientExternalApiException $e) {
            // Mit Backoff wiederholen - neu stempeln und neu dispatchen
            throw new RecoverableMessageHandlingException($e->getMessage(), previous: $e);
        } catch (PermanentValidationException $e) {
            // Sofort in Validierungs-DLQ routen, nicht wiederholen
            throw new UnrecoverableMessageHandlingException($e->getMessage(), previous: $e);
        }
        // Alle anderen Exceptions verwenden die Standard-Retry-Strategie
    }
}

Eine Exception als UnrecoverableMessageHandlingException zu markieren, bewirkt, dass Messenger die Retry-Strategie vollständig überspringt und den Envelope direkt an den Failure-Transport weiterleitet. Als RecoverableMessageHandlingException signalisiert, dass Retries fortgesetzt werden sollen.

Die Transport-Konfiguration teilt DLQ-Ziele nach Fehlerklasse auf:

framework:
    messenger:
        failure_transport: failed_default
        transports:
            failed_default:
                dsn: '%env(REDIS_DSN)%/failed:default'
            failed_validation:
                dsn: '%env(REDIS_DSN)%/failed:validation'

Kombiniert mit einem benutzerdefinierten Stamp, der die ursprüngliche Exception-Klasse und die Anzahl der Versuche aufzeichnet, hat dein Ops-Team eine DLQ, in der jeder Eintrag handlungsrelevant ist: Validierungsfehler gehen in einen Datenbehebungs-Workflow, transiente Fehler können mit messenger:failed:retry gebündelt wiederholt werden, und permanente Infrastrukturfehler erhalten einen separaten Alert-Schwellenwert.

Doctrine Connection-Pool-Tuning für Worker-Pools

Das ist der Fehlermodus, den die meisten Teams zuletzt entdecken - meistens unter unerwarteter Last. Jeder Messenger-Worker-Prozess hält mindestens eine Doctrine-Verbindung für die Dauer seines Lebens offen. Mit der Standard-Doctrine-DBAL-Konfiguration und einem typischen PostgreSQL-max_connections von 100 verbrauchen zehn Supervisor-Worker mit je drei Verbindungen und ein gleichzeitiger Webserver-Pool bereits sechzig Verbindungen, bevor jeglicher Burst-Traffic eintrifft.

Die Doctrine-Messenger-Middleware, die Verbindungen bei der Handler-Ausführung automatisch öffnet, verschlimmert das Problem: Wenn dein Handler fünf Abfragen abfeuert und PostgreSQL unter Contention steht, hält die Middleware die Verbindung für die gesamte Handler-Dauer ausgecheckt - was andere Worker blockiert, die auf eine Verbindung aus einem Pool warten, der bereits voll ist.

Die Lösung hat drei Teile. Erstens, füge die doctrine-Middleware zu jedem Transport hinzu, um sicherzustellen, dass Verbindungen zwischen Nachrichten ordnungsgemäß geschlossen werden:

framework:
    messenger:
        buses:
            messenger.bus.default:
                middleware:
                    - doctrine_transaction
                    - doctrine_ping_connection
                    - doctrine_close_connection

Die doctrine_close_connection-Middleware schließt die Verbindung explizit nach jeder verarbeiteten Nachricht und gibt sie an den Pool zurück. Ohne das akkumulieren langlebige Worker Idle-Verbindungen, die PostgreSQL gegen max_connections zählt, aber Doctrine als "verfügbar" betrachtet.

Zweitens, begrenze die Verbindungslebensdauer pro Worker in config/packages/doctrine.yaml:

doctrine:
    dbal:
        connection_factory:
            sslmode: 'prefer'
        options:
            !php/const PDO::ATTR_PERSISTENT: false
        keepSlave: false

Drittens, führe diese Abfrage auf deiner PostgreSQL-Instanz aus, um die tatsächliche Verbindungsverteilung sichtbar zu machen, bevor du jemals Worker-Zahlen in Supervisor anpasst:

SELECT application_name, state, count(*) 
FROM pg_stat_activity 
WHERE datname = current_database()
GROUP BY application_name, state
ORDER BY count DESC;

Wenn du viele idle-Verbindungen von deinem Worker-Anwendungsnamen siehst, ist doctrine_close_connection nicht konfiguriert oder deine Pool-Grenze ist zu hoch. Wenn du idle in transaction siehst, hält ein Handler eine Transaktion über einen langsamen Netzwerkaufruf offen - isoliere diesen Handler und verschiebe die Doctrine-Operation, bis nach dem externen Aufruf.

Transport-Wahl: In-Memory vs. Redis vs. AMQP unter Last

Für Produktionssysteme mit anhaltendem Volumen ist die Transport-Wahl wichtig, jenseits des offensichtlichen Haltbarkeits-Kompromisses.

In-Memory-Transport ist nur für Entwicklung und Integrationstests geeignet. Unter jeder Produktionslast verliert er Nachrichten bei Worker-Neustart und bietet keine Sichtbarkeit in die Queue-Tiefe.

Redis-Transport ist der richtige Standard für die meisten Symfony-Teams. Er bietet Persistenz (mit appendonly yes), hohen Durchsatz und eine native Queue-Tiefen-Metrik, die sich sauber mit Grafana integriert. Für die meisten Systeme unter 50.000 Nachrichten pro Minute sättigt Redis als letztes - der Engpass ist fast immer die Handler-Logik oder Downstream-Abhängigkeiten.

AMQP (RabbitMQ) fügt Mehrwert, wenn du Fan-out-Routing benötigst - eine Nachricht an mehrere Konsumenten - oder wenn du Exchange-Level-Dead-Lettering mit TTL-basiertem Retry-Scheduling auf Broker-Ebene statt auf Anwendungsebene möchtest. Der Symfony AMQP-Transport unterstützt Dead-Letter-Exchanges nativ:

framework:
    messenger:
        transports:
            async:
                dsn: '%env(AMQP_DSN)%'
                options:
                    exchange:
                        name: app
                        type: direct
                    queues:
                        messages:
                            arguments:
                                x-dead-letter-exchange: app.dlx
                                x-message-ttl: 30000

Für Systeme, bei denen ein Redis-Ausfall zu inakzeptablem Datenverlust in der Queue führen würde, bietet AMQP mit gespiegelten Queues stärkere Haltbarkeitsgarantien. Für die meisten B2B-SaaS-Anwendungen ist Redis mit aktivierter Persistenz ausreichend und betrieblich einfacher.

Supervisord-Konfiguration für Produktions-Worker-Pools

Die richtige Worker-Anzahl zu finden, erfordert Kenntnis der Verteilung der Message-Verarbeitungszeiten, nicht nur des Durchschnitts. Ein Handler mit einer p99-Latenz von 800ms bei der gleichen Worker-Anzahl wie ein Handler mit p99 von 50ms produziert unter Burst-Last ein völlig anderes Queue-Tiefenverhalten.

Eine Supervisord-Konfiguration, die diese Unterschiede berücksichtigt, verwendet separate Programme pro logischer Nachrichtenkategorie:

[program:messenger-default]
command=php /var/www/html/bin/console messenger:consume async --time-limit=3600 --memory-limit=256M
numprocs=4
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/messenger-default.log
stopwaitsecs=60

[program:messenger-external-api]
command=php /var/www/html/bin/console messenger:consume external_api --time-limit=3600 --memory-limit=256M
numprocs=2
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/messenger-external-api.log
stopwaitsecs=60

--time-limit=3600 bewirkt, dass jeder Worker nach einer Stunde sauber neu startet. Das ist unverzichtbar, um Memory-Creep in langlebigen PHP-Prozessen zu verhindern - ohne Zeitlimit werden Handler, die über Tausende von Nachrichten Objekte im Speicher akkumulieren, irgendwann das --memory-limit mitten in einer Nachricht überschreiten.

stopwaitsecs=60 gibt Workers Zeit, ihre aktuelle Nachricht zu beenden, bevor Supervisor SIGKILL sendet. Ohne es könnte Supervisor einen Worker mitten in einer Transaktion beenden und eine Nachricht in einem mehrdeutigen Zustand hinterlassen.

Für Systeme, bei denen die Verarbeitungszeit stark variiert - Jobs, die gelegentlich zehn Minuten dauern, neben Jobs, die in Millisekunden abgeschlossen sind - solltest du separate Transport-Queues und Supervisor-Programme für langlebige Handler in Betracht ziehen. Das verhindert, dass langsame Jobs den Rückstand an schnellen blockieren - das asynchrone Äquivalent von Head-of-Line-Blocking.

Die Muster, die sich gegenseitig verstärken

Einzeln betrachtet adressiert jedes dieser Muster einen Fehlermodus. Kombiniert ergeben sie einen Worker-Pool, der sich selbst drosselt, wenn Downstream-Systeme unter Druck stehen, bei nicht behebbaren Nachrichten schnell versagt, Fehler in handlungsrelevante Queues weiterleitet und keine Datenbankverbindungen belegt, die er gerade nicht aktiv nutzt.

Wenn dein Messenger-Deployment Stresszeichen zeigt - wachsende Queue-Tiefe unter Last, unerklärliche Datenbankverbindungs-Spitzen oder Worker-Prozesse in Retry-Schleifen - ist ein Code-Qualitäts-Audit oft der schnellste Weg, um zu identifizieren, welches Muster fehlt und was die Sanierungspriorität sein sollte. Diese Konfigurationen benötigen einen Nachmittag, um korrekt implementiert zu werden; sie in einem Produktions-Incident zu diagnostizieren, dauert erheblich länger.

Melde dich unter hello@wolf-tech.io oder besuche wolf-tech.io, wenn du deine Messenger-Architektur besprechen möchtest, bevor es der nächste Incident für dich tut.