Runbook voor een LLM-storing: detectie, escalatie, postmortem
Wanneer een extern Large Language Model (LLM) uitvalt, crasht niet alleen een afzonderlijke microservice, maar degradeert direct de functionele intelligentie van een complete applicatie. Hoewel de architecturale pijler van robuuste softwareontwerp voorziet in circuits en fallbacks, ontbreekt in de praktijk vaak de operationele handleiding die vastlegt hoe technici handelen tijdens actieve uitval. Zonder gestructureerd proces leidt een incident tot chaotische communicatie, vertraagde mitigerende maatregelen en gemiste claims op Service Level Agreements. Raadpleeg het ankerartikel over robuuste integraties om te begrijpen hoe deze operationele runbook-procedures naadloos aansluiten op het bredere systeemontwerp.
Dit artikel fungeert als het operationele runbook bij LLM-storingen. Het verbindt signalen uit observability direct met acties voor incident-response, escalatiepaden en postmortem-analyses. Dit artikel behandelt de technische fallback-laag zelf niet; zie de gids voor graceful degradation bij LLM-uitval voor de implementatie van reserve-modellen en degradatiestrategieën. Dit artikel behandelt niet welke SLA-cijfers je in een contract moet bedingen; zie ons overzicht van SLA en uptime bij LLM-providers voor het opstellen van contractuele garanties.
1. Het runbook als operationeel artefact
Een runbook is geen statische documentatie die eenmalig bij het opleveren van een project wordt geschreven. Het is een levend, versiebeheerd artefact dat direct beschikbaar moet zijn voor de dienstdoende site reliability engineer (SRE) of ontwikkelaar. Het eigenaarschap van het runbook ligt primair bij het team dat verantwoordelijk is voor het beheer van de LLM-integratie-infrastructuur of API-gateway.
Het runbook treedt in werking op het moment dat geautomatiseerde bewaking gecontroleerde drempelwaarden overschrijdt of wanneer eindgebruikers een significante afname van functionaliteit melden die niet door reguliere applicatiefouten wordt verklaard. Om te zorgen dat de instructies accuraat blijven, geldt de verplichting dat elke wijziging in de API-architectuur, routing-logica of fallback-providers binnen 24 uur wordt doorgevoerd in de runbook-procedures. Elk incident vormt de directe aanleiding om het stappenplan te herzien.
2. Fase 1: Detectie en signaalanalyse
Faalmodus
In deze fase centreert de faalmodus zich rondom het onvermogen om tijdig vast te stellen of een verhoogd foutpercentage veroorzaakt wordt door een externe providerstoring (zoals infrastructuuruitval, model-degradatie of capaciteitsproblemen bij de leverancier) dan wel door een interne fout in de eigen applicatiecode (zoals ongeldige JSON-payloads, gecorrumpeerde API-sleutels of overschreden prompt-tokenlimieten).
Detectie
Automatische detectie berust op het continu analyseren van observability-signalen bij het API-eindpunt. Maak onderscheid tussen harde providerfouten (zoals HTTP statuscodes 500, 502, 503 en 504), rate-limit-fouten (HTTP 429) en applicatiefouten (HTTP 400 of 422). Voor het correct inrichten van telemetriepijplijnen en logstructuren verwijzen we naar de gids voor observability en logging, waar uitgelegd wordt hoe je gedetailleerde metrieken verzamelt. Wanneer HTTP 5xx-fouten gedurende een voortschrijdend venster van 60 seconden de drempel van 5% overschrijden, is er sprake van een potentiële providerstoring.
Naast foutpercentages zijn latency-percentielen kritieke indicatoren. Een plotselinge stijging van het P99- of P95-latency-niveau wijst vaak op verstopping bij de provider voordat er daadwerkelijk HTTP-foutcodes worden geretourneerd. Bekijk de benchmark-handleiding voor latency-percentielen om te bepalen welke meetwaarden representatief zijn voor jouw specifieke workloads.
Onderscheid tijdelijke uitval (zoals netwerkspikes of kortstondige herstarts) van structurele storingen door het analyseren van de foutfrequentie en de respons-headers van de provider (zoals Retry-After). Als 80% van de verzoeken gedurende meer dan drie achtereenvolgende minuten faalt, betreft het een structurele storing.
// Provider-onafhankelijke detectielus voor LLM-endpoint gezondheid
type HealthStatus struct {
IsHealthy bool
ErrorRate float64
P95LatencyMs int64
FailureReason string
}
func EvaluateLLMEndpoint(metrics MetricsWindow, timeoutBudgetMs int64) HealthStatus {
// Definieer de kritieke alarmdrempels
const maxErrorThreshold = 0.05 // 5% fouten toegestaan
const maxP95LatencyMs = 4500 // 4.5 seconden P95 limiet
if metrics.TotalRequests == 0 {
return HealthStatus{IsHealthy: true, ErrorRate: 0, P95LatencyMs: 0}
}
errorRate := float64(metrics.FailedRequests) / float64(metrics.TotalRequests)
// Foutpad 1: HTTP 5xx of netwerkfouten overschrijden drempel
if errorRate > maxErrorThreshold {
return HealthStatus{
IsHealthy: false,
ErrorRate: errorRate,
P95LatencyMs: metrics.P95LatencyMs,
FailureReason: "PROVIDER_ERROR_RATE_EXCEEDED",
}
}
// Foutpad 2: Latency overschrijdt het gestelde deadline-budget
if metrics.P95LatencyMs > maxP95LatencyMs || metrics.P95LatencyMs > timeoutBudgetMs {
return HealthStatus{
IsHealthy: false,
ErrorRate: errorRate,
P95LatencyMs: metrics.P95LatencyMs,
FailureReason: "LATENCY_BUDGET_EXHAUSTED",
}
}
return HealthStatus{
IsHealthy: true,
ErrorRate: errorRate,
P95LatencyMs: metrics.P95LatencyMs,
}
}Mitigatie
Zodra de detectielus een afwijking vaststelt, isoleert de applicatie direct de uitgaande stroom naar de defecte provider. De automatische bewaking registreert het exacte tijdstip van het incident, verzamelt de meest recente 100 fout-trace-IDs en markeert de provider in het interne statusdashboard als onbeschikbaar. Hierdoor wordt voorkomen dat vervolgverzoeken vastlopen in lange wachttijden.
Kosten van de mitigatie
- Latency: De detectielus introduceert een minimale verwerkingstijd van circa 1 tot 5 milliseconden per geaggregeerde metriek-evaluatie.
- Geld: Extra opslag- en verwerkingskosten voor gedetailleerde distributed tracing en hoge-resolutie metriekverameling.
- Complexiteit: Vereist een robuuste telemetrie-infrastructuur (zoals Prometheus/Grafana of OpenTelemetry) en zorgvuldig afgestelde alarmeringsregels om valse positieven te voorkomen.
3. Fase 2: Escalatie en communicatie
Faalmodus
De faalmodus in deze fase omvat het uitblijven van tijdegeschakelde actie, het verkeerd inschatten van de impact op de bedrijfsvoering, of onduidelijke, tegenstrijdige communicatie naar interne belanghebbenden en externe gebruikers tijdens een actieve onderbreking.
Detectie
Escalatie wordt geactiveerd zodra de automatische mitigatie (zoals een circuit breaker) langer dan 5 minuten actief blijft, of wanneer het verlies van functionaliteit direct invloed heeft op kritieke bedrijfsprocessen (zoals betalingsverwerking of klantenservice-automatisering).
Mitigatie
Het escalatieproces volgt een strikt gedefinieerde escalatieladder:
- Niveau 1: Geautomatiseerde melding (T0). Pager-melding naar de on-call engineer via geautomatiseerde alarmering op basis van de detectiemetrieken.
- Niveau 2: Incident Commander (T+10 min). Indien de storing na 10 minuten niet automatisch is opgelost of opgevangen door transparante fallbacks, neemt de Incident Commander de leiding over de operationele coordinatie.
- Niveau 3: Stakeholder-notificatie (T+15 min). Informeer het product- en serviceteam. Werk de interne statuspagina bij.
- Niveau 4: Externe communicatie (T+30 min). Publicering van een incidentmelding op de openbare statuspagina voor externe gebruikers indien de dienstverlening zichtbaar is aangetast.
Tijdens een actieve storing is een nauwkeurige registratie van gegevens essentieel voor het afhandelen van de contractuele verplichtingen van de leverancier. SLA-verwachtingen zijn vastgelegd in contracten, maar vereisen tijdens uitval specifieke handelingen: leg timestamps van de eerste mislukte call vast, bewaar de HTTP-responscodes en de Unieke Request-IDs van de provider, en genereer een geaggregeerd rapport van de totale downtime. Voor de juridische en administratieve details van claims lees je het advies over AI-contracten en SLA-claims waarin stap voor stap staat hoe je bewijslast verzamelt voor creditclaims en hoe de communicatieplicht richting leveranciers werkt.
Kosten van de mitigatie
- Latency: Geen directe invloed op runtime applicatielatency.
- Geld: Operationele kosten voor piketdiensten (on-call vergoedingen) en communicatieplatforms (zoals PagerDuty of Statuspage).
- Complexiteit: Organisatorische overhead; vereist regelmatige training van het incident-response team en duidelijke draaiboeken voor communicatie.
4. Fase 3: Tijdelijke mitigatie en operationalisering
Faalmodus
In deze fase bestaat de faalmodus uit het volledig blokkeren van applicatie-workflows doordat het systeem afhankelijk blijft van een onbeschikbaar model, of juist het overbelasten van de reserve-infrastructuur door een ongecontroleerde, abrupte omschakeling.
Detectie
Het systeem detecteert dat de primaire provider niet binnen de gestelde time-out reageert of herhaaldelijk foutmeldingen retourneert. Retries en exponentiële backoff proberen kortstondige netwerk-flikkeringen op te vangen. Om te voorkomen dat retries de uitvallende provider verder overbelasten, raadpleeg je de richtlijnen voor retries en backoff voor de juiste configuratie van jitter en maximale retry-pogingen.
Wanneer de circuit breaker uitslaat, treedt het tijdelijke mitigatieprotocol in werking. Dit protocol schakelt over naar een secundaire route of activeert een functionele degradatiemodus.
Mitigatie
Afhankelijk van de ernst en het type van de storing worden de volgende mitigerende maatregelen stapsgewijs geactiveerd:
- Fallback-provider inschakelen: Schakel het API-verkeer om naar een alternatieve LLM-aanbieder of een lokaal gehost model.
- Modeldegradatie: Schakel over van een zwaar, trager model naar een lichter, sneller model van dezelfde of een andere provider om de basisfunctionaliteit te behouden. (Indien de vraag "welk model" moet worden gekozen in de applicatiearchitectuur opkomt, verwijzen we voor modelselectiecriteria naar de informatie op modelkeuze per taak op hub.llmnet.nl).
- Functionele degradatie: Bied een versimpelde ervaring aan, zoals het tonen van gecachte antwoorden, het uitschakelen van complexe hulpmiddelen (tool use) of het tonen van een statische melding aan de gebruiker.
Bij het uitvoeren van retries en het overschakelen naar reserve-providers ontstaat het risico dat een verzoek dubbel wordt verwerkt bij de provider als de oorspronkelijke call wel is ontvangen maar de respons is vertraagd. Een idempotency key voorkomt dat herhaalde API-calls onbedoelde neveneffecten veroorzaken. Bekijk het overzicht over idempotentie bij LLM-calls voor de exacte implementatie van unieke sleutels op API-niveau.
Daarnaast moet elk verzoek strak begrensd worden door een deadline-budget om te voorkomen dat draden in de applicatie eindeloos blijven wachten op een trage provider. Zie de gids voor timeouts en cancellation om te leren hoe je time-outs cascading door je complete keten kunt doorvoeren.
| Mitigatiestrategie | Impact op Latency | Financiële Impact | Complexiteit van Implementatie |
|---|---|---|---|
Kosten van de mitigatie
- Latency: Omschakelen naar een secundaire provider brengt netwerkoverheads met zich mee. Caching verlaagt de latency juist aanzienlijk.
- Geld: Dubbele infrastructuurkosten voor het aanhouden van standby-capaciteit bij alternatieve providers of het draaien van een eigen gateway. Een gateway vereist dedicated resources; zie het handboek voor het zelf hosten van een LLM-gateway voor meer informatie over het beheren van je eigen routinglaag.
- Complexiteit: Prompts moeten zodanig zijn gestandaardiseerd dat ze identiek functioneren op verschillende modelarchitecturen.
5. Fase 4: Postmortem en incidentevaluatie
Faalmodus
De faalmodus in de postmortem-fase is het optreden van een herhaling van dezelfde storing doordat actiepunten niet helder worden toegewezen, of het ontstaan van een afrekencultuur ("blame culture") waardoor technici fouten verbergen in plaats van de onderliggende systeemzwaktes aan te pakken.
Detectie
De postmortem-fase start automatisch binnen 24 tot 48 uur na het formeel afschalen van de incidentstatus naar "Opgelost".
Mitigatie
Een effectieve postmortem volgt het principe van een blameless culture. Het doel is niet het aanwijzen van een schuldige, maar het identificeren van systeemfouten, ontbrekende monitoring en tekortkomingen in de automatisering. De postmortem-analyse doorloopt de volgende stappen:
- Tijdlijnreconstructie: Breng gedetailleerd in kaart wanneer de eerste afwijking optrad (T0), wanneer het alarm afging (T1), wanneer de mitigatie werd ingezet (T2) en wanneer de dienstverlening volledig hersteld was (T3).
- Analyse van de runbook-performance: Evalueer expliciet of de stappen in dit runbook correct zijn uitgevoerd. Waar traden vertragingen op? Waren de alarmdrempels te strikt of juist te ruim ingesteld?
- Toewijzen van actiepunten: Elk verbeterpunt krijgt één specifieke eigenaar en een harde streefdatum voor oplevering. Actiepunten variëren van het aanpassen van de alarmering tot het herstructureren van de fallback-logica.
- Validatie door middel van testen: Controleer of de doorgevoerde verbeteringen daadwerkelijk werken door het nabootsen van een providerstoring in een testomgeving. Lees het handboek voor het testen van LLM-integraties om te leren hoe je gelaagde storingssimulaties en chaos engineering toepast op API-koppelingen.
Wanneer tijdens het incident bleek dat een wijziging in de prompt-structuur de oorzaak was van de fouten (bijvoorbeeld doordat de provider een nieuwe modelversie uitrolde die anders reageerde op bestaande prompts), moet een snelle rollback naar een eerdere promptversie mogelijk zijn. Raadpleeg het artikel over versiebeheer voor prompts in code om te zorgen dat prompt-wijzigingen atomic en traceerbaar zijn opgenomen in je CI/CD-pijplijn.
Kosten van de mitigatie
- Latency: Geen invloed op runtime latency.
- Geld: Tijdsinvesteringskosten van het engineeringteam voor het analyseren van de logs, het schrijven van het rapport en het uitvoeren van herstelwerkzaamheden.
- Complexiteit: Beheer van actielijsten en het continu up-to-date houden van de test- en uitwijkdocumentatie.
6. Checklist voor de dienstdoende engineer
Gebruik onderstaande beknopte checklist bij het daadwerkelijk optreden van een LLM-storing:
- [ ] Verifieer de storingsbron: Controleer telemetrie op 5xx-fouten, time-outs en P99-latency. Sluit interne fouten (4xx, ongeldige sleutels) uit.
- [ ] Controleer de geautomatiseerde mitigatie: Bepaal of de circuit breaker correct is geactiveerd en of het verkeer automatisch naar de fallback-provider of degradatiemodus is omgeleid.
- [ ] Informeer belanghebbenden: Schaal op volgens de escalatieladder en werk de statuspagina bij indien de onderbreking langer duurt dan 5 minuten.
- [ ] Leg bewijslast vast: Sla logbestanden, request-IDs, foutcodes en exacte tijdsintervallen op ter ondersteuning van latere SLA-creditclaims.
- [ ] Monitor herstel: Zodra de providerstoring is opgelost, controleer je via de detectielus of het foutpercentage onder de 1% zakt voordat je het verkeer geleidelijk (canary release) terugzet naar de primaire provider.
- [ ] Plan de postmortem: Plan binnen 48 uur na het incident de evaluatiesessie en bereid de tijdlijnreconstructie voor.
