Naar de inhoud
Recognized byLaravelMatch je projectContact

Een Laravel-queue die dagenlang geen jobs verwerkt. Terwijl de worker gewoon draait.

Een Laravel-applicatie verwerkt plotseling geen jobs meer. De queue loopt vol, maar de worker draait volgens de server gewoon. Sterker nog: start je de queue-worker handmatig, dan worden de jobs keurig verwerkt. Wat is hier aan de hand? Een bijzondere casus uit onze dagelijkse praktijk als managed-hostingprovider.

Een Laravel-queue die dagenlang geen jobs verwerkt. Terwijl de worker gewoon draait.

Een Laravel-applicatie verwerkt plotseling geen jobs meer. De queue loopt vol, maar de worker draait volgens de server gewoon. Sterker nog: start je de queue-worker handmatig, dan worden de jobs keurig verwerkt. Wat is hier aan de hand? Een bijzondere casus uit onze dagelijkse praktijk als managed-hostingprovider.

Laravel is één van de frameworks waarmee veel klanten van Cyberfusion werken. We hosten Laravel-applicaties voor klanten, bouwen zelf software met Laravel én helpen developers bij technische problemen die verder gaan dan de hostingomgeving alleen.

Soms levert dat een puzzel op waar je als developer behoorlijk gek van kunt worden. Zoals bij deze klant, die ontdekte dat een belangrijke Laravel-queue al dagenlang geen jobs meer verwerkte. De bijbehorende worker draaide gewoon, er waren geen duidelijke foutmeldingen, en jobs werden prima verwerkt wanneer je handmatig een worker startte.

Samen met de klant gingen we op onderzoek uit.

Een Laravel-worker die draait, maar niets doet

De applicatie van onze klant gebruikt Laravel-queues om taken op de achtergrond uit te voeren. Denk aan het verwerken van gegevens, periodieke controles en andere werkzaamheden die niet tijdens een HTTP-request plaats hoeven te vinden.

Daarvoor draaien meerdere queue-workers, elk verantwoordelijk voor een eigen queue. De klant merkte dat het aantal wachtende jobs steeds verder opliep. Eén van de belangrijkste queues verwerkte blijkbaar al dagenlang niets meer.

Het vreemde: de daemon (het achtergrondproces waarbinnen de queue-worker draait) stond gewoon aan.

Nog vreemder: wanneer de klant op dezelfde server hetzelfde Laravel-commando handmatig uitvoerde, werden de wachtende jobs onmiddellijk verwerkt. Zodra dat handmatig gestarte proces stopte, begon de queue opnieuw op te lopen.

Waarom deed de worker onder de daemon niets?

Wat zegt Laravel zelf?

Een logische eerste stap is kijken wat Laravel en de procesmanager eigenlijk doen.

Een Laravel-queue-worker is een langlopend PHP-proces. Met bijvoorbeeld php artisan queue:work start je een proces dat voortdurend nieuwe jobs uit de queue ophaalt en uitvoert.

Dat proces blijft - onder normale omstandigheden - bestaan totdat het expliciet wordt gestopt, zichzelf beëindigt (bijvoorbeeld door --max-time), of door een exception omvalt. Daarom gebruik je in productie meestal een procesmanager, zoals Supervisor of systemd, om de worker te starten en waar nodig opnieuw op te starten.

Op ons hostingplatform Core hoeven klanten hier niets voor te doen: wanneer je een Laravel-project aanmaakt, wordt de queue-worker achter de schermen automatisch geconfigureerd en gestart.

Maar: een draaiend PHP-proces betekent niet automatisch dat Laravel nog jobs verwerkt.

Een proces kan vasthangen terwijl het ergens op wacht. Bijvoorbeeld op een databasequery of een externe API. Voor de procesmanager is er dan ogenschijnlijk niets aan de hand. De worker is immers niet gestopt.

De logs maakten het alleen maar vreemder

We begonnen met het bekijken van de logbestanden en de daadwerkelijk draaiende processen.

De eerste queue bleek nog regelmatig jobs te verwerken. In de logs zagen we bijvoorbeeld:

11:21:11 ScheduledJob  20s DONE
11:21:11 ScheduledJob  RUNNING
11:21:28 ScheduledJob  17s DONE
11:21:28 ScheduledJob  RUNNING
11:21:45 ScheduledJob  17s DONE
11:21:45 ScheduledJob  RUNNING

Daar leek weinig mis mee.

Bij de tweede queue-worker was het anders. Volgens de logs had de worker sinds 10 juli om 18:25 uur geen enkele job meer afgerond.

Dat strookte alleen niet met wat de klant had waargenomen. Volgens de klant waren er tot 12 juli nog jobs verwerkt. Zowel bij ons als bij de klant werd meerdere malen "huh?" geroepen.

We besloten de vastgelopen daemon voorlopig niet te herstarten. Daarmee zouden de jobs waarschijnlijk weer verwerkt worden, maar zouden we ook de kans verliezen om de oorzaak te achterhalen.

Een Laravel-job die al zes dagen bezig was

Door het PHP-proces achter de daemon verder te onderzoeken, vonden we uiteindelijk iets opmerkelijks.

De worker was niet per se gestopt met het verwerken van jobs. Hij was alleen nog steeds bezig met dezelfde job die hij op 10 juli had opgepakt.

Het ging om een job die een SSL-certificaat controleerde. Daarvoor deed de applicatie een call naar de externe API van een externe leverancier.

De job wachtte dus al bijna een week op een API-call die maar niet werd afgerond. Omdat deze Laravel-worker jobs achter elkaar verwerkt, kwam hij nooit toe aan de volgende job in de queue.

En inderdaad: de externe API - die de applicatie aanroept - had rond die tijd een storing. Waarschijnlijk was de request daardoor blijven hangen.

"Maar waarom blijft die request dan hangen? De HTTP-client van Laravel heeft toch een standaard-timeout?" hoor ik sommigen denken. Klopt, maar: de applicatie gebruikte Guzzle voor de HTTP-request. En die heeft standaard dan weer géén timeout.

Dat verklaarde de symptomen:

  • De daemon bleef op running staan, omdat het PHP-proces nog bestond.
  • Er verschenen geen nieuwe afgeronde jobs in de logs, omdat de worker 'vastzat' in één job.
  • De queue bleef groeien, omdat er geen volgende jobs meer werden opgepakt.
  • De queue-worker handmatig draaien werkte wel, omdat daarmee een volledig nieuw worker-proces werd gestart.

Een enkele vastgelopen HTTP-verbinding had zo een complete queue-worker tot stilstand gebracht.

Hoe ontdek je waarop een vastgelopen PHP-proces wacht?

Een PHP-proces dat niet meer reageert, vertelt via de applicatielogs niet waar het op wacht. Gelukkig kun je op Linux rechtstreeks onderzoeken wat een proces op systeemniveau doet.

Je hebt roottoegang nodig en moet het proces-ID (PID) van de vastgelopen worker. Met bijvoorbeeld ps aux kun je zoeken naar het php artisan queue:work-proces.

1. Bekijk wat het PHP-proces doet

strace -p $PID

Met strace zie je welke system-calls (syscalls) het proces uitvoert. Bij een proces dat op netwerkverkeer wacht, kun je bijvoorbeeld een recvfrom-syscall tegenkomen.

Daarmee zie je dat het proces probeert gegevens van een socket te ontvangen. Maar met welke externe server communiceert die socket?

Daarvoor kijken we naar de file descriptor (FD) die bij de syscall hoort.

2. Zoek de bijbehorende socket

Linux maakt de open file descriptors van een proces inzichtelijk via /proc.

ls -l /proc/$PID/fd

De uitvoer kan bijvoorbeeld een verwijzing bevatten zoals:

12 -> socket:[12345678]

Dat betekent dat file-descriptor 12 verwijst naar een socket met inode 12345678.

3. Achterhaal het externe IP-adres

Met die socket-inode kun je de bijbehorende TCP-verbinding opzoeken:

grep 12345678 /proc/$PID/net/tcp6 /proc/$PID/net/tcp

In de uitvoer staan onder andere het lokale adres (local_address) en het externe adres (rem_address), beide in hexadecimale notatie.

4. Zet het hexadecimale adres om naar een IP-adres

Bij IPv4 kun je het hexadecimale adres omzetten naar decimale notatie met een combinatie van sed en awk. Omdat Linux IPv4-adressen hier in little-endian bytevolgorde weergeeft, moet je de volgorde van de vier bytes omdraaien.

Bijvoorbeeld, met 0100007F:

printf '%d.%d.%d.%d\n' $(echo 0100007F | sed 's/../0x& /g' | awk '{print $4,$3,$2,$1}')

Dit geeft 127.0.0.1 terug.

Bij IPv6 is de conversie iets ingewikkelder. Daarvoor kun je bijvoorbeeld dit Python-script gebruiken.

Ook het poortnummer wordt hexadecimaal weergegeven. Dat kun je eenvoudig omzetten met printf:

printf '%d\n' "0x01BB"

Dat geeft 443 terug, de standaardpoort voor HTTPS.

Zo kun je achterhalen met welk extern IP-adres en welke poort een PHP-proces communiceert (of op vasthangt).

Belangrijk: dit onderzoek voer je uit vóórdat je het vastgelopen proces herstart. Na een herstart verdwijnen de file-descriptors die je nodig hebt om de oorzaak te achterhalen.

Maar waarom werkte alles dan nog tot 12 juli?

Er bleef één raadsel over.

De vastgelopen worker was sinds 10 juli bezig met dezelfde job. Toch wist de klant zeker dat er tot 12 juli nog jobs werden verwerkt.

Ook daarvoor vonden we, na veel hoofdpijn, een verklaring.

De applicatie was eerder overgezet van Supervisor naar een alternatieve manier om queue-workers te draaien: systemd. Tijdens die overgang waren beide procesmanagers tijdelijk naast elkaar actief.

Dat is op zichzelf geen probleem: meerdere Laravel-workers kunnen dezelfde queue verwerken, zolang de queue-backend en configuratie dat ondersteunen.

Tot 12 juli draaide er dus niet één, maar twee workers. Terwijl de worker onder de nieuwe daemon toevallig was vastgelopen, bleef de worker onder Supervisor gewoon jobs verwerken.

Toen de oude worker gestopt werd, bleef alleen de vastgelopen worker over. Vanaf dat moment werden er helemaal geen jobs meer verwerkt.

Waar kun je als Laravel-developer rekening mee houden?

Deze casus laat zien dat een draaiende Laravel-worker niet per definitie een functionerende Laravel-worker is. Met een paar voorzorgsmaatregelen voorkom je dat één vastgelopen job een queue compleet blokkeert.

1. Gebruik je Guzzle rechtstreeks? Stel zelf timeouts in.

De klant gebruikte Guzzle rechtstreeks voor zijn API-call. Dat is een belangrijk onderscheid, omdat Guzzle 7 standaard geen timeout instelt.

Maak je rechtstreeks gebruik van Guzzle, bijvoorbeeld binnen een Laravel-job, configureer dan zelf zowel een connection-timeout als een request-timeout.

$client = new \GuzzleHttp\Client();

$response = $client->get('https://example.com/api', [
    'connect_timeout' => 5,
    'timeout' => 30,
]);

Hiermee mag het opzetten van de verbinding (connect_timeout) maximaal vijf seconden duren en de volledige HTTP-request (timeout) maximaal dertig seconden. Onder connect_timeout worden bijvoorbeeld ook DNS-lookups geschaard.

Gebruik je in plaats van Guzzle Laravel's eigen HTTP-facade? Dan zijn er al standaardwaarden ingesteld: 10 seconden voor het opzetten van de verbinding en 30 seconden voor de volledige request.

Http::connectTimeout(5)
    ->timeout(30)
    ->get('https://example.com/api');

Ook daar kun je de waarden dus zelf aanpassen, maar het probleem van een ontbrekende request-timeout speelt standaard niet.

2. Verwar --max-time niet met --timeout

Laravel heeft twee queue-worker-opties die geregeld met elkaar worden verward:

  • --max-time=3600: laat een worker maximaal een uur jobs verwerken. In combinatie met Supervisor of systemd kan de worker vervolgens opnieuw worden gestart. Dit helpt om opgebouwd geheugengebruik, bijvoorbeeld door memoryleaks, periodiek op te ruimen.
  • --timeout=60: beperkt hoe lang één job mag draaien. Wordt deze tijd overschreden, dan beëindigt Laravel normaal gesproken de worker.

Belangrijk: --max-time onderbreekt geen vastgelopen job. De worker controleert pas na afloop van een job of hij zijn maximale levensduur heeft bereikt. Een job die zes dagen blijft hangen, wordt dus niet na een uur afgebroken door --max-time=3600.

De oplettende lezer zal zich afvragen: waarom greep --timeout in deze casus niet in?

Dat heeft te maken met de manier waarop PHP en het besturingssysteem omgaan met bepaalde blokkerende I/O-operaties.

Laravel gebruikt voor zijn jobtimeouts onder andere signalen via de PHP-extensie PCNTL. In bepaalde situaties kan een proces echter vastzitten in een blokkerende socketoperatie, waardoor het timeoutmechanisme de job niet op het verwachte moment kan onderbreken.

Dit is een bekende beperking. Laravel waarschuwt er zelf expliciet voor in de documentatie over queue-timeouts:

Sometimes, IO blocking processes such as sockets or outgoing HTTP connections may not respect your specified timeout.

Laravel noemt Guzzle daarbij zelfs specifiek als voorbeeld en adviseert om afzonderlijke connection- en request-timeouts te configureren.

Een timeout op de Laravel-worker is dus geen garantie dat iedere blokkerende netwerkoperatie daadwerkelijk wordt afgebroken.

Gebruik --timeout om de uitvoeringstijd van jobs te begrenzen, en houd deze waarde lager dan retry_after, zodat dezelfde job niet opnieuw beschikbaar komt terwijl de oorspronkelijke worker nog bezig is.

De belangrijkste voorzorgsmaatregel blijft daarom om externe HTTP-requests óók op het niveau van de HTTP-client te begrenzen.

3. Monitor of jobs daadwerkelijk worden verwerkt

Een procesmanager kan controleren of een worker draait, maar weet niet noodzakelijk of die nog jobs verwerkt. Daarom is het verstandig om ook de wachttijd van jobs, de omvang van queues en eventuele vastgelopen jobs te monitoren.

Laravel Horizon biedt hiervoor uitgebreide mogelijkheden bij Redis-queues. Ook buiten Horizon kun je zulke controles inrichten. We zien dat klanten hier vaak Better Stack of Nightwatch voor gebruiken.

Een draaiend proces vertelt niet het hele verhaal

Bij Cyberfusion werken we dagelijks met Laravel, zowel in onze eigen software als in de applicaties die klanten bij ons hosten. Daardoor kunnen onze engineers ook meedenken wanneer een probleem zich ergens tussen Laravel, PHP, Linux en de onderliggende infrastructuur bevindt.

In deze casus had een simpele herstart de queue weer aan het werk gekregen. Maar dan hadden we niet geweten waarom de worker was vastgelopen, en had dezelfde situatie zich later opnieuw kunnen voordoen.

Het interessante aan dit soort problemen is dat alle afzonderlijke onderdelen op het eerste gezicht correct lijken te functioneren. De daemon draaide, Laravel gaf geen duidelijke fouten, en een handmatig gestarte worker verwerkte de jobs probleemloos. Toch stond de queue al dagenlang stil.

Daar komt de weerbarstigheid van een productieomgeving bij. Complexe applicaties en hun infrastructuur zijn voortdurend in beweging. Configuraties veranderen, processen worden vervangen, en tijdens migraties kunnen oude en nieuwe situaties tijdelijk naast elkaar bestaan. Zo ook hier, waarbij twee workers draaiden. Dat maakt het achterhalen van de oorzaak soms ingewikkelder dan de symptomen doen vermoeden.

Daarom loont het om zulke problemen systematisch te onderzoeken. Door niet alleen naar de logs te kijken, maar ook naar de daadwerkelijke processen, hun onderlinge samenhang en waar ze precies op wachten, werd uiteindelijk duidelijk wat er speelde.

Zeker nu AI steeds vaker helpt bij het schrijven en debuggen van code, blijft het belangrijk om zelf scherp te blijven. AI kan hypotheses aandragen en het onderzoek versnellen, maar je moet nog altijd zelf kunnen beoordelen of een verklaring past bij wat er daadwerkelijk in een productieomgeving gebeurt.

Over de auteur
William David Edwards

William David Edwards

Founder of Cyberfusion

William David Edwards is the founder of Cyberfusion, the truly managed hosting provider for web professionals. With a background in DevOps and infrastructure engineering, he helps web professionals spend less time managing servers and more time building websites and applications.