Incident documentation/Report Template

From Wikitech
Jump to navigation Jump to search

This is a template for an Incident Report. Replace these notes in italics with your own text. Save the incident report as a subpage of the Incident documentation, named in this style: YYYYMMDD-$NameOfService.

document status: draft

The status field should be one of {{irdoc-draft}}, {{irdoc-review}}, {{irdoc-final}}. When you're happy with the state of your draft, change it to {{irdoc-review}}, the incident review working group will contact you (see steps on Incident documentation).

Summary

This is a short (<= 1 paragraph) of what happened. While keeping it short, try to avoid assuming deep knowledge of the systems involved, and also try to differentiate between proximate causes and root causes. Please ensure to remove private information.

Impact

Who was affected and how? For user-facing outages, estimate: How many queries were lost? How many users were affected, and which populations (editors only? all readers? just particular geographies?) were affected? etc. Be as specific as you can, and do not assume the reader already has a good idea of what your service is and who uses it.

Detection

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

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

If automated, please add the relevant alerts to this section. Did the appropriate alert(s) fired? Was the alert volume manageable? Did they point to the problem with as much accuracy as possible?

Timeline

This is a step by step outline of what happened to cause the incident and how it was remedied. Include the lead-up to the incident, as well as any epilogue, and clearly indicate when the user-visible outage began and ended.

All times in UTC.

  • 00:00 (TODO) OUTAGE BEGINS
  • 00:04 (Something something)
  • 00:06 (Voila) OUTAGE ENDS

Conclusions

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

The following sub-sections should have a couple brief bullet points each.

What went well?

  • for example: automated monitoring detected the incident, outage was root-caused quickly, etc

What went poorly?

  • for example: documentation on the affected service was unhelpful, communication difficulties, etc

Where did we get lucky?

  • 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?

  • for example: 2 SREs and 1 software engineer troubleshooting the issue plus 1 incident commander

Links to relevant documentation

Where is the documentation that someone responding to this alert should have (runbook, plus supporting docs). If that documentation does not exist, there should be an action item to create it.

Actionables

Explicit next steps to prevent this from happening again as much as possible, with Phabricator tasks linked for every step.

NOTE: Please add the #wikimedia-incident Phabricator project to these follow-up tasks and move them to the "follow-up/actionable" column.

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