A runbook should help a responder move from a specific symptom to a safe decision.
A runbook should help a responder move from a specific symptom to a safe decision. It is not a catalogue of every command the system accepts. Write it for someone with the expected access and skills who may be tired, unfamiliar with the component or unable to reach the author.
Start with the alert and impact
Name the triggering signal, affected journey and conditions under which the procedure applies. Link to the relevant dashboard and explain which observation distinguishes this problem from similar symptoms. Include an owner, last review date and the severity or escalation reference. Keep access to the runbook available if the main application is unavailable.
State prerequisites and stop conditions
Describe required permissions, environment selection and approvals for consequential actions. Say when the procedure must stop and escalate: unexplained data changes, missing backups or a result that contradicts the diagnosis. Do not embed secrets in the document. Link to the approved access mechanism and give a fallback contact.
Make actions verifiable
For each step, record purpose, expected result and next branch. Prefer bounded diagnostic actions before state changes. Where a restart, replay or failover is involved, explain its effect on in-flight work and duplicate processing. Include how to reverse the change if possible and how to recognise when reversal is unsafe.
Close with recovery and follow-up
Verify the customer journey and any queued or missed work. Record the incident reference, actions taken and outstanding repairs. Test the runbook with another team member in a safe exercise and improve every ambiguous step. Keep it close to the owning service so deployment or architecture changes trigger review. A short tested procedure is more dependable than a long unmaintained document.
- Related service
- On-call for startups without a dedicated SRE team
- Incident severity levels: a practical escalation matrix
Frequently asked questions
Should a runbook contain shell commands?
Where useful, include reviewed commands with prerequisites, scope and expected results; commands alone are not a procedure.
How long should it be?
Long enough to support the specific decision path without burying essential actions in unrelated detail.
Who should test it?
Someone other than the author with the access and skills expected of a real responder.
What if the steps do not match reality?
Stop at the defined boundary, preserve evidence and escalate rather than improvising an unbounded recovery.
When should it be updated?
After relevant changes, exercises and incidents reveal new behaviour or missing assumptions.
Bring the scope. We will help make it buildable.
Share the user journey, integrations and launch constraints. We can clarify the scope and prepare an estimate with assumptions and exclusions.
Further reading
On-call for startups without a dedicated SRE team
A small team can operate a useful on-call system if its promises match its staffing and tooling.
Incident severity levels: a practical escalation matrix
Incident severity should describe current or credible business impact, not how alarming a log message looks.
Rollback or hotfix during a production incident
During an incident, choose the action most likely to restore acceptable service with controlled risk.