Write incident playbooks in Sentry dashboard markdown widgets
Stop switching between wikis and monitoring tools. Put your triage runbooks directly inside the dashboards your team already watches.
Before you start
Accounts & access
- Sentry account with at least one project sending data
Knowledge
- Basic familiarity with Sentry Dashboards
- Basic markdown syntax (headings, links, lists)
1 Create an incident dashboard
Go to Dashboards and either pick an existing dashboard or click Create Dashboard. A good naming convention is Service - Incidents, for example Checkout API - Incidents. This dashboard will hold both the widgets your team watches and the playbook that tells them what to do during an incident.
Custom dashboards guide
2 Add a text widget for your playbook
Click Add Widget, then select Create Custom Widget. In the widget builder, open the Type dropdown and choose Text (Markdown). Give the widget a clear title like Incident Playbook or On-Call Runbook so it stands out on the dashboard. You will see a freeform text area where you can write markdown. This is where your playbook will live.
Widget builder reference
3 Write a structured triage playbook
Use the text area to outline the steps your team should follow when something goes wrong. A strong playbook answers three questions: What is happening? How do I confirm it? What do I do about it? Structure your playbook with markdown headings for each phase and use links to point directly into Sentry pages like your Issues stream or Trace Explorer. Keep the language direct and action-oriented. During an incident, your team needs clear instructions, not explanations.
## High Error Rate Playbook
### 1. Confirm the spike
- Check the error rate widget on this dashboard
- Open [Issues][1] and filter by unresolved
### 2. Identify the root cause
- Open the latest error and read the stack trace
- Check Seer on the issue page for root causes
- Look at linked traces for upstream failures
### 3. Mitigate
- Roll back a bad deploy via your CI/CD pipeline
- Check third-party dependency status pages
- Post an update in #incidents on Slack
### 4. Follow up
- Assign the issue to the owning team
- Link the Sentry issue to a Jira or Linear ticket
[1]: https://sentry.io/orgredirect/organizations/:orgslug/issues/
4 Arrange the playbook next to your metric widgets
A playbook is most useful when it sits right next to the data it references. Drag widgets to arrange your dashboard so the playbook is adjacent to the charts your team checks during an incident. For example, put error rate and transaction duration charts in the first row, then place the playbook text widget and a top errors table in the second row. When your playbook says check the error rate widget above, the engineer's eyes move up a few inches instead of switching tabs. This spatial proximity turns a generic runbook into a contextual, self-contained incident response tool.
That's it.
Your playbook lives where the data does.
When the next incident hits, your team opens one dashboard and finds the steps and the metrics in the same view. No wiki hunting, no stale docs.
- Created a triage playbook inside a Sentry dashboard text widget
- Structured a runbook with markdown headings, links, and lists
- Paired playbook widgets with the metric widgets they reference
Pro tips
- 💡 Use markdown headings in your text widget to create visual hierarchy. Engineers scan faster during incidents when steps are clearly separated.
- 💡 Add a Last updated line at the bottom of each playbook widget so your team knows how fresh the runbook is.
Common pitfalls
- ⚠️ Don't write novels. A playbook that takes five minutes to read during an incident defeats the purpose. Keep steps short and actionable.
- ⚠️ Don't forget to update playbook links when you reorganize projects or rename dashboards. Broken links during an incident waste precious minutes.
- ⚠️ Don't skip the follow-up section in your playbook. Triage is only half the job. Without a clear follow-up process, the same incident will repeat.
Frequently asked questions
) as long as the image is hosted at a publicly accessible URL. Sentry won't host the image for you, but it will render it in the widget.What's next?
Fix it, don't observe it.
Get started with the only application monitoring platform that empowers developers to fix application problems without compromising on velocity.