Runbook: cum scrii instrucțiuni care funcționează la 3 dimineața

Un runbook este un document operațional care permite cuiva care nu a scris codul să răspundă la un incident specific fără să improvizeze. Conține pașii de diagnostic, mitigare și escalare pentru un scenariu concret: un serviciu care nu pornește, o bază de date care refuză conexiuni, un job care a rămas blocat.

Cuvântul vine din cultura sysadmin a anilor 1990, când operatorii de data center aveau cu adevărat caiete cu proceduri pe birou. Astăzi, un runbook trăiește în repo sau într-un wiki, dar problema pe care o rezolvă este aceeași: cunoașterea operațională nu trebuie să stea blocată în capul unei singure persoane.

Ce este un runbook mai exact?

Un runbook este o procedură pas-cu-pas pentru un incident sau o operațiune predefinită. Nu este documentație generală despre cum funcționează sistemul și nu este un tutorial. Este un ghid de acțiune cu un singur scop: cineva îl deschide când ceva s-a stricat sau urmează să fie schimbat, și îl închide după ce situația este rezolvată.

Distincția față de documentație generală contează practic. Documentația explică arhitectura și deciziile de design. Runbook-ul spune ce faci în minutul doi al unui incident. Dacă un coleg nou preia garda și Postgres refuză conexiuni, nu are timp să citească toată documentația; are nevoie de runbook-ul specific pentru acel simptom.

• Scop unic. Fiecare runbook acoperă un singur tip de incident sau operațiune. Nu un manual general, ci o procedură pentru un caz specific.
• Limbaj direct. Pașii sunt formulați ca instrucțiuni, nu ca descrieri. „Rulează comanda X" bate „se poate rula comanda X".
• Auditoriu explicit. Runbook-ul presupune că cititorul știe să acceseze serverul și să ruleze comenzi de bază, dar nu știe nimic specific despre acest serviciu.

Care este formatul minimal al unui runbook util?

Patru secțiuni sunt suficiente pentru orice incident operațional obișnuit:

• Simptom. Ce a văzut persoana care a deschis runbook-ul: alertă, eroare în log, comportament vizibil pentru utilizator. Formulat ca un titlu de incident, nu ca o descriere vagă.
• Diagnostic. Una-două comenzi sau verificări care confirmă cauza. Nu o investigație exhaustivă, ci o confirmare rapidă că ești pe calea corectă.
• Mitigare. Pașii care rezolvă sau limitează impactul imediat. Poate fi un restart, o configurare temporară sau o redirecționare de trafic. Mitigarea nu trebuie să fie soluția definitivă.
• Escalare. Cine se sună dacă mitigarea nu funcționează. O persoană sau un canal, cu un număr de telefon sau un alias, nu un link la o organigramă.

Opțional, adaugi o secțiune de context dacă incidentul are o cauză recurentă deja cunoscută, sau un link către stack-ul de observabilitate relevant. Dar nu mai mult: un runbook lung este un runbook care nu va fi citit la presiunea unui incident real.

Cum îl ții actualizat după fiecare incident?

Cea mai frecventă greșeală nu este că runbook-ul lipsește, ci că există dar este vechi. Un runbook scris acum șase luni și neatins de atunci reflectă sistemul de acum șase luni. Dacă ai schimbat portul unui serviciu, ai migrat un Postgres sau ai adăugat un nivel de autentificare, runbook-ul vechi te poate îndruma greșit exact când contează mai mult.

Regula simplă: runbook-ul se actualizează imediat după orice incident în care a fost folosit sau în care s-a dovedit insuficient. Nu în săptămâna viitoare, nu în sprintul următor. Detaliile precise dispar în ore. Post-mortem-ul de incident este cel mai bun moment: ai cauzele proaspete în minte, știi exact unde runbook-ul s-a potrivit și unde nu. Actualizarea durează zece minute dacă o faci atunci.

O practică utilă este să adaugi la finalul runbook-ului un câmp „Ultima utilizare reală" cu data și ce s-a schimbat față de versiunea anterioară. Runbook-urile care nu au fost utilizate în mai mult de un an și nu au fost actualizate deliberat sunt candidați la arhivare sau revizuire.

Cum sunt structurate runbook-urile la crawlerra?

Runbook-urile noastre trăiesc în repo-ul de operațiuni, alături de configurațiile de infrastructură. Structura fiecăruia urmează același șablon: simptom, diagnostic, mitigare, escalare. Nu inventăm formate speciale per serviciu. Când un runbook devine mai complex, este un semnal că fie sistemul are o problemă de arhitectură, fie că un runbook a fost transformat într-un document de documentație generală.

La momentul ultimei revizii, aveam 20 de runbook-uri active¹. Fiecare alertă din stack-ul de observabilitate are un runbook corespondent; dacă o alertă nu are runbook, nu se activează în producție. Politica asta ne-a forțat de câteva ori să simplificăm alertele: dacă nu poți scrie un runbook pentru o alertă, probabil alerta nu este suficient de concretă.

Actualizarea intră în post-mortem-ul fiecărui incident care a folosit un runbook: rate limiting-ul depășit, un job n8n care a eșuat tăcut, o conexiune Postgres care a căzut intermitent. Fiecare astfel de incident îl forțează pe cine intervine să verifice că procedura corespunde realității actuale. Asta este disciplina care ține runbook-urile vii, nu un ritual de revizuire periodică.

Care este capcana cea mai frecventă?

Un runbook care nu a fost testat sub presiune reală este aproape inutil. Poți scrie proceduri care par logice în liniștea biroului și care se dovedesc incomplete sau greșit ordonate când cineva le urmează la 3 dimineața, obosit, cu o pagină de alerte deschise în browser. Motivul este că autorul runbook-ului cunoaște implicit o mulțime de detalii pe care nu le-a scris pentru că îi par evidente.

• Pași care presupun cunoaștere implicită. „Conectează-te la serverul de producție" fără să specifici cum, cu ce cheie, la ce adresă, este o instrucțiune incompletă pentru cineva care nu a mai făcut asta.
• Comenzi netestare pe sistemul actual. Un runbook scris pe mediul de dev care nu a fost verificat pe prod poate eșua la primul pas din cauza diferențelor de configurare.
• Escalare neclară sau cu date expirate. „Sună-l pe Andrei" este inutil dacă Andrei a plecat din echipă. Escalarea trebuie să fie un rol sau un canal, nu o persoană specifică.
• Un singur runbook pentru mai multe scenarii. Tentația de a combina cazuri similare produce un document ambiguu. Două scenarii diferite cu cauze diferite merită runbook-uri separate, chiar dacă pașii se suprapun parțial.
• Runbook scris, dar nelinkuit din alertă. Dacă alerta nu include direct link-ul la runbook, în mijlocul incidentului oamenii caută în loc să acționeze. Legătura alertă, runbook este obligatorie, nu opțională. Conectarea cu SLA-ul agreat ajută să înțelegi cât de urgent trebuie să fie răspunsul.

1. Numărul de runbook-uri active în repo-ul de operațiuni crawlerra la momentul ultimei revizii (mai 2026). [ops.runbooks_count]