Incident Forensics

​

What gets recorded

• Rule evaluations — one row per rule evaluated against a check result. Captures rule type (consecutive_failures, response_time, …), region, inputs, outputMatched flag, and the policy snapshot hash.
• State transitions — one row per status edge walked (WATCHING → TRIGGERED, TRIGGERED → CONFIRMED, CONFIRMED → RESOLVED, …). Carries triggeringEvaluationIds, checkId, policySnapshotHashHex, and engineVersion. The reason field distinguishes detection-engine causes (trigger, confirm, resolve, auto_clear, reopen) from user-driven actions (manually_resolved).
• Policy snapshots — content-addressed by SHA-256 of the policy JSON. The exact policy that was active at evaluation time, even if the monitor has been edited since.

​

Endpoints

​

CLI

devhelm forensics timeline <incident-id>
devhelm forensics trace <check-id>
devhelm forensics snapshot <hash-hex>
devhelm forensics evaluations --monitor-id <uuid> --only-matched
devhelm forensics transitions --monitor-id <uuid> --from 2026-04-01T00:00:00Z

​

SDKs

import {Devhelm} from '@devhelm/sdk'

const client = new Devhelm({token: process.env.DEVHELM_API_TOKEN!})

const timeline = await client.forensics.incidentTimeline(incidentId)
const trace = await client.forensics.checkTrace(checkId)
const snapshot = await client.forensics.policySnapshot(hashHex)

const {data: evals} = await client.forensics.monitorRuleEvaluations(monitorId, {
  onlyMatched: true,
  ruleType: 'consecutive_failures',
})

from devhelm import Devhelm

client = Devhelm(token=os.environ["DEVHELM_API_TOKEN"])

timeline = client.forensics.incident_timeline(incident_id)
trace = client.forensics.check_trace(check_id)
snapshot = client.forensics.policy_snapshot(hash_hex)

page = client.forensics.monitor_rule_evaluations(
    monitor_id,
    only_matched=True,
    rule_type="consecutive_failures",
)

​

MCP tools

• get_incident_timeline(incident_id) — replay why an incident fired
• get_check_trace(check_id) — inspect a single check execution
• get_policy_snapshot(hash_hex) — fetch the exact policy active at a past moment
• list_monitor_rule_evaluations(monitor_id, ...) — audit rule firings
• list_monitor_transitions(monitor_id, ...) — reconstruct monitor lifecycle

​

Use cases

• Incident replay: a customer asks “why did we get paged?” — the timeline endpoint returns the check, policy, and rules involved, no log scraping needed.
• Policy change review: before editing a trigger rule, fetch the snapshot hash that fired the last incident and diff it against the new policy.
• False-positive audit: list rule-evaluations?onlyMatched=true for a monitor over the last 7 days to spot noisy rules.
• Cross-region analysis: filter rule-evaluations?region=us-east to see how one region contributed to confirmation.

​

Retention

​

Next steps