Skip to main content
The forensic model records every decision the detection engine makes as an immutable database row. Use it to answer “why did this incident fire?”, “what policy was in effect?”, and “which check caused the transition?” — without re-running the data.

​
What gets recorded

Three row types are written for every check that flows through detection:
  • 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.
All rows are tagged with organizationId and the originating checkId, so you can thread a single check execution across both writes.

​
Endpoints

All endpoints are read-only and live under /api/v1/forensics/:
EndpointPurpose
GET /forensics/incidents/{id}/timelineFull timeline for an incident: transitions + triggering evaluations + active policy snapshot
GET /forensics/traces/{checkId}Everything recorded for a single check execution
GET /forensics/policy-snapshots/{hashHex}Fetch a policy snapshot by its SHA-256 hash
GET /forensics/monitors/{id}/rule-evaluationsPaginated list of rule evaluations for a monitor (filters: ruleType, region, onlyMatched, from, to)
GET /forensics/monitors/{id}/transitionsPaginated list of state transitions for a monitor (filters: from, to)

​
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
Every command supports --output json|yaml|table and the standard auth flags.

​
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',
})

​
MCP tools

The DevHelm MCP server exposes the same read path to AI agents:
  • 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
See the MCP tools reference for full signatures.

​
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

Row typeRetentionNotes
Rule evaluations30 daysHigh-volume hypertable (~288M rows/day at scale); compressed at 7 days
State transitions2 yearsLow-volume, high audit value
Policy snapshotsIndefiniteContent-addressed by SHA-256; deleting would orphan references

​
Next steps

Incident Timeline

Human-facing view of an incident’s lifecycle — status changes, updates, and notifications.

Incident Policies

Configure the trigger and recovery rules that forensics record.

MCP Tools Reference

Let an AI agent query the forensic model directly.

API Reference

Full schema for every forensic endpoint.