How incident.io measures incidents

Know exactly what your MTTR and other incident metrics mean, wherever you report on them.

Every incident metric in incident.io comes from two things: timestamps, which record when the key moments in an incident happened, and duration metrics, which measure the time between two of them. The definitions on this page are the ones we use everywhere, so whether you’re looking at Insights, pulling data from the API, or reporting from a data warehouse or an engineering metrics platform, MTTR means the same thing.

You can configure timestamps and duration metrics in Settings → Response → Lifecycle, on the Timestamps and metrics tab.

Timestamps

Default timestamps

Every account starts with these timestamps. The statuses mentioned are our defaults. If you’ve renamed or replaced them, the same rules apply to yours.

Timestamp	When it’s set
Declared at	When the incident is created
Accepted at	When the incident moves out of triage into an active status
Declined at	The first time the incident enters Declined
Merged at	The first time the incident enters Merged
Canceled at	The first time the incident enters Canceled
Resolved at	The last time the incident moves from an active or paused status to a post-incident or closed one
Impact started at	Set manually by a responder
Identified at	The first time the incident leaves Investigating
Fixed at	The first time the incident leaves Fixing
Documented at	The first time the incident leaves Documenting
Reviewed at	The first time the incident leaves Reviewing
Closed at	The last time the incident enters Closed

An incident declared straight into an active status never passes through triage, so it has no Accepted at value.

Rules for custom timestamps

A timestamp you create is either set manually, or set automatically the first or last time an incident enters or leaves a status you choose. A “first” rule keeps its original value if the incident passes through the status again. A “last” rule moves forward each time.

Manual values take precedence

Once someone has set a timestamp by hand, whether in the dashboard or through the API, we won’t overwrite it when the status changes. That’s what lets a responder correct Declared at to when the incident really started, or fill in Impact started at after the fact.

Reopened incidents

Reopening an incident doesn’t clear any timestamps. When it’s resolved again, Resolved at moves to the new resolution time, and Closed at moves when it’s closed again. Timestamps with “first” rules keep their original values.

Imported incidents

When you create a retrospective incident, Declared at records when you ran the import, not when the incident actually happened, so set any timestamps you report on in incident_timestamp_values when you create each one.

Duration metrics

A duration metric measures the time from one timestamp to another. New accounts start with three:

Duration metric	From	To
Incident duration	Declared at	Resolved at
Time to detect	Impact started at	Declared at
Time to fix	Declared at	Fixed at

Incident duration is the duration shown for each incident across the product. You can define as many other metrics as you need, between any two timestamps, such as Impact started at to Resolved at for a time to restore that starts when customers were first affected.

How a duration is calculated

• The value is the time from start to end, in whole seconds.
• Paused time isn’t counted by default. If you’d rather include the time an incident spent paused, edit the metric under Duration metrics on the Timestamps and metrics tab and turn on Include paused time.
• Both timestamps need a value. If either is missing, the incident simply has no value for that metric.
• The end has to come after the start. If it doesn’t, again the incident has no value for that metric. Turning on Enable validation stops responders saving timestamps in the wrong order in the first place. See Incident timestamps.
• Values update when timestamps change. Edit a timestamp and every metric that uses it is recalculated. Change which timestamps a metric uses and it’s recalculated for every incident.

Which incidents are counted

Test and tutorial incidents are left out everywhere by default, in both Insights and the API.

Declined, canceled, and merged incidents are left out by default too, on the basis that they either weren’t real incidents or are already counted under another one. In Insights you can bring them back in from the filter bar, and the Time spent and Follow-ups dashboards include them by default.

Private incidents don’t appear in Insights by default either. If your account has any, turn on Include private incidents on a dashboard to add the ones you have access to. Through the API, a key only sees private incidents if it has the View all incident data permission. See API keys.

In Insights

Duration metric panels place each incident in your date range by its Declared at time, and show the median by default, though you can chart the mean and percentiles too. Incidents with no value for the metric, or a value of zero, aren’t included.

When you break a metric down by a multi-select custom field, an incident with several values counts once under each of them.

Linking incidents to services

Metrics by service or team come from custom fields on the incident. Use a Catalog-backed field, such as Affected services, so every incident points at the same service records as the rest of your tools. See Custom fields.

For incidents created from alerts, an incident template can set these fields from the alert’s attributes. When you create an alert route, we suggest these for any custom field backed by the same Catalog type as one of your alert attributes.

In the API

The list incidents and show incident endpoints return both timestamps and durations on each incident.

incident_timestamp_values lists every timestamp in your account, in order. Each entry has the timestamp’s id, name, and rank, and a value when the timestamp is set. A timestamp that isn’t set has no value.

duration_metrics lists every duration metric, with the metric’s id and name, the value_seconds for this incident, and a status:

status	Meaning
success	value_seconds is the current value
calculating	Both timestamps are set, and the value is being calculated
timestamps_missing	One or both timestamps aren’t set
invalid_timestamps	The end timestamp is before the start

Only use value_seconds when status is success. With other statuses, it may be missing or hold an earlier value.