What Is a Runbook?

A runbook is a short set of steps for a failure you have seen before. When the alert fires, the person on call should be able to follow it without already knowing the system. If the page starts with a tour of the architecture, it is a document about the service, and the steps are buried in it.

A postmortem is the record of one incident: what happened, and what is still true after the fix. A runbook is what you want the next person to do. The postmortem earns a line in the runbook only when the next person should act differently. The rest of the story stays in the postmortem.

What belongs on the page

• The alert or symptom that means this is the right page
• The checks, in order, and what each result means
• The action that ends the incident, and who is allowed to take it
• When to stop and wake someone else

Leave out the history and the list of every command that might someday apply. A page of forty commands is a search box. At 2am the person will run the first familiar one.

One failure per page

The README explains how to work on the service on a normal day. The runbook explains what to do when a specific thing is already wrong. "Billing service" is not a runbook. "Nightly billing job started twice" is. If you have never seen the failure, you do not have the steps, and a guessed page is worse than no page.