You are browsing a read-only backup copy of Wikitech. The live site can be found at

Incident response/Full report template: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
m (Krinkle moved page Incident documentation/-Report Template to Incident response/Full report template without leaving a redirect: Move to Incident response so that the "-" hack isn't needed, simplifying parsing of incident docs)
No edit summary
Line 1: Line 1:
{{Note|To use this template:
This is the template for an incident report.
* Go to '''[[Incident status]]'''
* To use it: Submit the form at [[Incident documentation]], then replace the marked placeholders with your own text.
* Fill in the "Full-length report" form to auto-create a report page with today's date.
* You should '''name''' it in this style: "''$NameOfService''".
* Save early, save often.
(Do not edit or copy this page directly.)|type=warning}}
* It will automatically be saved as a subpage of [[Incident documentation]], with the "YYYYMMDD-" timestamp as a prefix like the others.  
</noinclude>{{irdoc|status=<includeonly>draft</includeonly>}} <!--
</noinclude>{{irdoc|status=<includeonly>draft</includeonly>}} <!--
The status field should be one of:
The status field should be one of:

Revision as of 22:33, 20 April 2021

document status: draft


What happened, in one paragraph or less. Avoid assuming deep knowledge of the systems here, and try to differentiate between proximate causes and root causes.

Impact: Who was affected and how? In one paragraph or less. For user-facing outages, estimate: How many queries were lost? How many users were affected, or which populations (editors? readers? particular geographies?), etc. Do not assume the reader knows what your service is or who uses it.


Write a step by step outline of what happened to cause the incident, and how it was remedied. Include the lead-up to the incident, and any epilogue.

Consider including a graphs of the error rate or other surrogate.

Link to a specific offset in SAL using the SAL tool at (example)

All times in UTC.

  • 00:04 (Something something)
  • 00:06 (Voila) OUTAGE ENDS
  • 00:15 (post-outage cleanup finished)

TODO: Clearly indicate when the user-visible outage began and ended.


Write how the issue was first detected. Was automated monitoring first to detect it? Or a human reporting an error?

Copy the relevant alerts that fired in this section.

Did the appropriate alert(s) fire? Was the alert volume manageable? Did they point to the problem with as much accuracy as possible?

TODO: If human only, an actionable should probably be to "add alerting".


What weaknesses did we learn about and how can we address them?

What went well?

  • (Use bullet points) for example: automated monitoring detected the incident, outage was root-caused quickly, etc

What went poorly?

  • (Use bullet points) for example: documentation on the affected service was unhelpful, communication difficulties, etc

Where did we get lucky?

  • (Use bullet points) for example: user's error report was exceptionally detailed, incident occurred when the most people were online to assist, etc

How many people were involved in the remediation?

  • (Use bullet points) for example: 2 SREs and 1 software engineer troubleshooting the issue plus 1 incident commander

Links to relevant documentation

Add links to information that someone responding to this alert should have (runbook, plus supporting docs). If that documentation does not exist, add an action item to create it.


Create a list of action items that will help prevent this from happening again as much as possible. Link to or create a Phabricator task for every step.

  • To do #1 (TODO: Create task)
  • To do #2 (TODO: Create task)

TODO: Add the #Sustainability (Incident Followup) Phabricator tag to these tasks.