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 fuer asynchrone Verarbeitung - Webhook-Empfaenger, 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 fuenf Minuten einen Burst von 8.000 Webhook-Events, und dein Monitoring zeigt: Datenbankverbindungen erschoepft, 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-Verstaerker verwandelt. Retry-Logik, die fuer gelegentliche Fehler ausgelegt war, hat den Connection-Pool bei hoher Last gesaettigt. Ein einziges fehlerhaftes Event - genau die Art, die dein Schema-Validator nie vorhergesehen hat - wurde tausende Male wiederholt, waehrend legitime Nachrichten dahinter aufgestaut wurden.

Das sind keine Randfaelle. Das sind die vorhersehbaren Fehlermodi von Messenger-Deployments, die noch nicht fuer den Produktionsbetrieb gehaertet wurden. Die folgenden Muster installieren wir in Client-Systemen, die mehr als 1 Million Nachrichten pro Tag verarbeiten.

Das Kernproblem: Retry-Amplifikation und Transport-Backpressure

Symfony Messengers Standard-Retry-Konfiguration ist grosszuegig: drei Versuche mit einem Multiplikator von zwei, beginnend bei einer Sekunde. Fuer Systeme, die Dutzende Nachrichten pro Minute verarbeiten, ist das in Ordnung. Fuer Systeme unter anhaltender Last mit einer langsamen Abhaengigkeit - eine externe API mit 400ms durchschnittlicher Latenz, ein Doctrine-Listener, der bei jeder verarbeiteten Nachricht eine sekundaere Abfrage abfeuert - glaetten Retries die Last nicht, sie verstaerken sie.

Der kumulative Effekt ist ein Muster, das wir Retry-Amplifikation nennen: Eine fehlerhafte Nachricht loest drei Retry-Zyklen aus, jeder Retry belegt einen Worker-Prozess fuer die gesamte Retry-Verzoegerung, und waehrenddessen ziehen andere Worker weiterhin neue Nachrichten. Bei hohen Eingangsraten kann der Worker-Pool gesaettigt sein, bevor der Dead-Letter-Schwellenwert je erreicht wird.

Die Loesung hat zwei Teile: Rate Limiting auf Transport-Ebene, damit sich Worker basierend auf dem Zustand der Abhaengigkeiten 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 laesst sich sauber ueber einen benutzerdefinierten Middleware-Wrapper integrieren - genauer gesagt ueber 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, unabhaengig 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 ausdruecken, anstatt zu hoffen, dass der Downstream jeden Burst uebersteht.

Fuer Exponential Backoff mit Jitter - entscheidend, wenn der Downstream sich von einem Ausfall erholt und du einen Thundering Herd beim Wiederverbinden vermeiden moechtest - ueberschreibe 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 fuegt jedem Retry-Delay-Intervall bis zu 20% zufaellige Varianz hinzu. Mit einem Multiplikator von 2 beginnend bei einer Sekunde fallen Retry-Slots bei etwa 1s, 2s, 4s, 8s und 16s - mit genuegend 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 voellig 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 vollstaendig ueberspringt 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 urspruengliche 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 koennen mit messenger:failed:retry gebuendelt wiederholt werden, und permanente Infrastrukturfehler erhalten einen separaten Alert-Schwellenwert.

Doctrine Connection-Pool-Tuning fuer Worker-Pools

Das ist der Fehlermodus, den die meisten Teams zuletzt entdecken - meistens unter unerwarteter Last. Jeder Messenger-Worker-Prozess haelt mindestens eine Doctrine-Verbindung fuer 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-Ausfuehrung automatisch oeffnet, verschlimmert das Problem: Wenn dein Handler fuenf Abfragen abfeuert und PostgreSQL unter Contention steht, haelt die Middleware die Verbindung fuer die gesamte Handler-Dauer ausgecheckt - was andere Worker blockiert, die auf eine Verbindung aus einem Pool warten, der bereits voll ist.

Die Loesung hat drei Teile. Erstens, fuege die doctrine-Middleware zu jedem Transport hinzu, um sicherzustellen, dass Verbindungen zwischen Nachrichten ordnungsgemaess geschlossen werden:

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

Die doctrine_close_connection-Middleware schliesst die Verbindung explizit nach jeder verarbeiteten Nachricht und gibt sie an den Pool zurueck. Ohne das akkumulieren langlebige Worker Idle-Verbindungen, die PostgreSQL gegen max_connections zaehlt, aber Doctrine als "verfuegbar" 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, fuehre diese Abfrage auf deiner PostgreSQL-Instanz aus, um die tatsaechliche 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, haelt ein Handler eine Transaktion ueber 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

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

In-Memory-Transport ist nur fuer 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 fuer die meisten Symfony-Teams. Er bietet Persistenz (mit appendonly yes), hohen Durchsatz und eine native Queue-Tiefen-Metrik, die sich sauber mit Grafana integriert. Fuer die meisten Systeme unter 50.000 Nachrichten pro Minute saettigt Redis als letztes - der Engpass ist fast immer die Handler-Logik oder Downstream-Abhaengigkeiten.

AMQP (RabbitMQ) fuegt Mehrwert, wenn du Fan-out-Routing benotigst - eine Nachricht an mehrere Konsumenten - oder wenn du Exchange-Level-Dead-Lettering mit TTL-basiertem Retry-Scheduling auf Broker-Ebene statt auf Anwendungsebene moechtest. Der Symfony AMQP-Transport unterstuetzt 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

Fuer Systeme, bei denen ein Redis-Ausfall zu inakzeptablem Datenverlust in der Queue fuehren wuerde, bietet AMQP mit gespiegelten Queues staerkere Haltbarkeitsgarantien. Fuer die meisten B2B-SaaS-Anwendungen ist Redis mit aktivierter Persistenz ausreichend und betrieblich einfacher.

Supervisord-Konfiguration fuer 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 voellig anderes Queue-Tiefenverhalten.

Eine Supervisord-Konfiguration, die diese Unterschiede beruecksichtigt, 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 ueber Tausende von Nachrichten Objekte im Speicher akkumulieren, irgendwann das --memory-limit mitten in einer Nachricht ueberschreiten.

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

Fuer 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 fuer langlebige Handler in Betracht ziehen. Das verhindert, dass langsame Jobs den Rueckstand an schnellen blockieren - das asynchrone Aequivalent von Head-of-Line-Blocking.

Die Muster, die sich gegenseitig verstaerken

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, unerklaeliche Datenbankverbindungs-Spitzen oder Worker-Prozesse in Retry-Schleifen - ist ein Code-Qualitaets-Audit oft der schnellste Weg, um zu identifizieren, welches Muster fehlt und was die Sanierungsprioritat sein sollte. Diese Konfigurationen benoetigen einen Nachmittag, um korrekt implementiert zu werden; sie in einem Produktions-Incident zu diagnostizieren, dauert erheblich laenger.

Melde dich unter hello@wolf-tech.io oder besuche wolf-tech.io, wenn du deine Messenger-Architektur besprechen moechtest, bevor es der naechste Incident fuer dich tut.