Runbook

What is a runbook?

A runbook is a written procedure for one recurring operational task or one known failure, written plainly enough that someone who did not build the system can follow it at 3am.

Most runbooks answer a specific alert. Google's site reliability engineering practice calls the same thing a playbook: high-level instructions for responding to an automated alert, with the likely impact, a few debugging suggestions, and the actions that mitigate and resolve it. When a new alert is created, a matching runbook entry is usually written alongside it.

The point is speed under stress. Google's SRE teams found that writing the response down beforehand, rather than winging it, gives roughly a threefold improvement in mean time to repair (MTTR). A runbook is where a service level objective under threat turns into a concrete sequence of steps.

What a good entry contains

The value is in the specifics. A good entry names the alert it answers, the preconditions to check first, the exact copy-pasteable commands with real service and table names, a verification step that proves the fix worked, a rollback for when it makes matters worse, and the point where you stop and escalate. A step that says "check the data" helps no one; a step that names the query does.

In practice it looks like this. Say a nightly data pipeline fails to load yesterday's orders and the sales dashboard is stale. The runbook has you check the orchestrator for where the job failed, then the source API status. If the source is down you post that the dashboard is delayed upstream and wait; if it is healthy you rerun the job once, and because the load is idempotent a second run will not double the orders. You then verify row counts and data freshness, and if the rerun fails too you escalate to the data-platform on-call instead of attempting a manual backfill alone. Keep it short, because nobody reads a novel mid-incident and the details rot as fast as the system they describe.

From runbook to automation

Runbooks carry an honest tension: every step a machine can do reliably, a machine eventually should, so a good runbook slowly empties itself into scripts, a workflow engine, or the alerting tool. The "rerun once" step above is a prime candidate to automate away. The written version still earns its place, because it records why a step exists, which actions are safe to retry and which ones change data, and where a human has to decide. Automation without that context becomes a black box no one can debug, the same discipline behind data observability and DataOps. Disaster recovery is the sharp end of it, where a database failover runbook turns your recovery targets, RPO and RTO, into steps you can actually run.

When "runbook" means a script, not a document

Watch the word, because it names two different things. In Azure Automation a runbook is not a document at all. It is the executable unit itself: a PowerShell or Python script, or a graphical equivalent, that Azure runs to stop idle virtual machines, restart a stuck service, or scale a database on a schedule. So one term covers two artifacts. A runbook-as-document is read and carried out by a person; a runbook-as-script is run by the platform with nobody watching. Both encode a known procedure, so when someone says "the runbook," check which one they mean.