Deze pagina is gericht op Laravel 13 en Framework
v13.42.0. Het gaat niet over het basisgebruik van queues, maar over hoe retry-instellingen samenwerken en welke voorrang heeft.Aantal pogingen en retry-deadline scheiden
Een “poging” in Laravel is niet alleen een geslaagde aanroep vanhandle(). Ook onafgehandelde exceptions, release(), releases door middleware zoals WithoutOverlapping of RateLimited en timeouts verbruiken pogingen. Als je niets opgeeft, probeert de worker de job maar één keer.
Tries: het aantal pogingen begrenzen
Je kunt een limiet per job declareren met het attribuut Tries. De instelling op de job heeft voorrang op --tries van de worker.
tries(). Deze methode heeft voorrang op het attribuut Tries.
RetryFor: een tijdvenster opgeven
Om retries niet op aantal maar op de tijd sinds het in de queue plaatsen te begrenzen, gebruik je RetryFor. Een los positioneel argument is een aantal seconden, en je kunt ook minutes en hours als benoemde argumenten opgeven.
RetryFor legt de retry-deadline vast in de payload van de job. De worker start geen nieuwe pogingen meer voor een job waarvan de deadline verstreken is. Heeft de job een methode retryUntil() of een property retryUntil, dan heeft die voorrang op RetryFor. Bij jobs waarvoor retryUntil actief is, heeft de tijdgebonden deadline bovendien voorrang op Tries.
retryUntil() is geschikt wanneer de deadline van de inhoud van de job afhangt, zoals het verwachte hersteltijdstip van een externe dienst of een zakelijke deadline.
Een limiet voor onafgehandelde exceptions instellen
Soms wil je handmatigerelease()-aanroepen en releases tijdens het wachten op een lock blijven toestaan, maar snel laten falen als onafgehandelde exceptions zich blijven voordoen. Geef in dat geval Tries en MaxExceptions apart op.
MaxExceptions telt geen retries die door release() ontstaan.
Pogingen waarbij het proces crashte (bijvoorbeeld door geheugentekort) tellen standaard niet mee voor het aantal exceptions van MaxExceptions. Moeten crashes ook als exceptions tellen, voeg dan CountCrashesAsExceptions toe.
Het interval tussen retries instellen
Een job die een exception gooit, wordt normaal gesproken opnieuw in de queue vrijgegeven. De wachttijd tot de volgende poging stel je in met het attribuutBackoff of de methode backoff().
Vast interval
backoff(). backoff() heeft voorrang op het attribuut Backoff.
--backoff van de worker gebruikt.
Wachtende jobs vrijgeven met dezelfde backoff
Wil je een job later opnieuw uitvoeren zonder een exception te gooien, bijvoorbeeld omdat een externe API “in behandeling” teruggeeft, gebruik danreleaseUsingBackoff(). De job wordt vrijgegeven met de waarde uit zijn backoff-array die bij de huidige poging hoort. Zijn de waarden op, dan wordt de laatste gebruikt, en zonder backoff wordt de job direct vrijgegeven.
releaseUsingBackoff() hebben verschillende doelen.
- Bij een exception: de job kon niet worden verwerkt, dus Laravel geeft hem vrij met de backoff.
- Handmatig vrijgeven: de verwerking zelf is in orde, maar de job wordt later opnieuw uitgevoerd zodra de externe status verandert.
releaseUsingBackoff() komt uit Backoff of backoff() van de job. Wil je bij een handmatige release expliciet een andere wachttijd opgeven, gebruik dan release(seconden).
Gecombineerd voorbeeld
De volgende job wordt maximaal een uur lang opnieuw geprobeerd en staat tot 3 onafgehandelde exceptions toe. Bij exceptions en bij handmatige releases tijdens het wachten op de betaling gebruikt hij intervallen van 10, 30 en 60 seconden.RetryFor aanwezig is, gebruikt de worker de deadline in plaats van Tries(25) als normale limiet voor pogingen. Geef je beide op, bepaal dan of de tijdgebonden deadline of de limiet op aantal de hoofdregel is, en leg die bedoeling vast met tests. MaxExceptions geldt los van beide.
Voorrang van instellingen
Wanneer je instellingen van de job en de worker combineert, maakt de volgende volgorde het beslissen eenvoudiger.
Bestaat er een deadline via
retryUntil of RetryFor, dan geeft de worker die voorrang op het aantal uit tries. Gebruik je RetryFor en retryUntil() samen, dan wint de dynamische retryUntil().
Hoe je kiest
- Is de deadline voor het wachten op herstel van een externe dienst duidelijk, gebruik dan
RetryFor. Wordt de deadline pas tijdens runtime bepaald, gebruik danretryUntil(). - Voor API-rate-limits en het controleren van betaalstatussen gebruik je
BackoffenreleaseUsingBackoff(). - Wil je veel tijdelijke lock-wachttijden maar weinig echte exceptions toestaan, combineer dan
TriesenMaxExceptions. - Bij verwerkingen waarbij retries neveneffecten opstapelen, ontwerp je naast het aantal pogingen ook idempotentie en duplicaatcontrole aan de kant van de externe API.
Je kunt
Tries en RetryFor ook opgeven voor eventlisteners en notificaties in de queue. Controleer dat de payload van het doel dat je gebruikt hetzelfde retrycontract heeft.Referenties
- Officiële Laravel-documentatie: Max job attempts and timeout
- Officiële Laravel-documentatie: Time-based attempts
- Officiële Laravel-documentatie: Handmatig vrijgeven en
releaseUsingBackoff - Officiële Laravel-documentatie: Backoff voor mislukte jobs
- Attribuut
RetryFor - Attributen
Backoff,TriesenMaxExceptions Queue::getJobExpirationInteractsWithQueue::releaseUsingBackoff