Causal Events
The atomic unit of Incidentary's data model — a structured, attributed event that carries parent-child relationship metadata.
Causal Events
A causal event (CE) is the atomic unit of Incidentary's data model. It is a timestamped, attributed, structured record of a single unit of work — and, critically, it carries a reference to the event that caused it.
How causal events differ from logs
Logs are an append-only stream of timestamped text or JSON records. They are chronological — you can sort them by time — but they are not causal. A log entry does not know what triggered it.
Causal events carry a parent_ce_id field that references the upstream event that caused this one. This transforms a flat stream into a graph: you can traverse the chain of causality from any event back to the root.
Causal graph (simplified)
─────────────────────────
[ce: a1b2] api-gateway HTTP_IN GET /orders
│
├──► [ce: c3d4] order-service HTTP_IN GET /orders (parent: a1b2)
│ │
│ ├──► [ce: e5f6] inventory HTTP_OUT GET /stock (parent: c3d4)
│ └──► [ce: g7h8] pricing HTTP_OUT GET /price (parent: c3d4)
│
└──► [ce: i9j0] auth-service HTTP_OUT POST /validate (parent: a1b2)A log stream would give you these five entries in wall-clock order. It would not give you the graph.
What a causal event contains
| Field | Type | Description |
|---|---|---|
ce_id | UUID v4 | Unique identifier for this event |
trace_id | UUID v4 | Shared identifier for the entire causal chain |
parent_ce_id | UUID v4 or null | The CE that triggered this one; null for the root |
service_id | string | The serviceName from your SDK config |
wall_ts_ns | int64 | Wall-clock timestamp in nanoseconds since Unix epoch |
kind | enum | HTTP_IN or HTTP_OUT |
status | int | HTTP response status code |
duration_ns | int64 | Elapsed time in nanoseconds |
sdk_version | semver | SDK version that emitted this event |
Emission
Causal events are emitted by the SDK middleware automatically on every HTTP request. You do not write events manually. The SDK intercepts the request lifecycle and creates the CE before your handler runs and finalises it (with status and duration) after the response is sent.
Retention and the pre-arm window
Causal events are retained according to your workspace's retention policy. Events within the pre-arm window preceding an alert are always retained as part of the incident record, regardless of the general retention setting.
See Pre-Arm for details.