AI & Automation
Drafting a runbook to restart a failed service
A runbook is only useful if someone stressed at night can follow it. This guide walks through building a sample for restarting a failed service, with three decisions that make it safe and repeatable.
01
Step one: define trigger and scope
Begin by stating exactly when the runbook applies. Example: a web API service named orders-api stops answering its health check for five minutes. Write the trigger, the system it covers and what it must not touch, such as the database or neighboring services. Name the owner and the people who can approve running it. Add a one-line purpose so a reader can confirm they have the right document. A narrow scope prevents a restart procedure from becoming a catch-all, and it makes later automation simpler because each runbook maps to one clear condition and outcome.
02
Step two: order the checks and the action
List the steps in the sequence a careful responder would take. First confirm the failure: check the health endpoint and the service status. Next look at recent logs for an obvious cause, since a restart can hide evidence, and save a copy. Then perform the action itself, restarting orders-api, with the exact command written out. Finally wait a defined period and test the endpoint again. Mark which steps are read-only and which change state. That distinction lets a future tool run the checks automatically while pausing for a human before the restart itself.
03
Step three: set verification and fallback
Close the runbook with proof that the fix worked and a plan if it did not. Verification might be a passing health check for ten minutes and normal error rates on the dashboard. The fallback might be a single retry, then escalation to the named owner with the saved logs attached. Record the time, the person and the outcome in a short history so patterns emerge, such as the same service failing weekly. Review the document after each use and edit anything that confused the responder. A runbook improves through those small corrections far more than through any initial draft.