The Assembled Artifact

When an incident is triggered, Incidentary assembles a causal artifact from the events your services emitted around the time of the alert. This document explains what the artifact contains and how to read it.

What you are looking at

The artifact is a causal chain. Each step in the chain is a single captured operation — one inbound request, one outbound call, one job execution. Each step names its predecessor explicitly. There is no inference about what called what; every link in the chain was recorded at runtime by the SDK.

Frames

A frame is one step in the causal chain. Each frame corresponds to a depth level in the causal graph: depth 0 is where the trace began, depth 1 is what was called from there, depth 2 is what was called next, and so on.

Each frame shows:

• Service name: which service produced this event
• Operation type: what kind of operation (HTTP_IN, HTTP_OUT, QUEUE_PUBLISH, QUEUE_CONSUME, JOB_START, JOB_END, WEBHOOK_IN, WEBHOOK_OUT)
• Status: HTTP status code or equivalent (200, 503, etc.)
• Duration: how long the operation took
• Timestamp: when it occurred

Gaps

A gap is a node in the chain whose parent was named but not captured. It appears as a placeholder in the artifact wherever a causal link is missing.

A gap means: "something called the next step, but the calling service's SDK was not running at that moment."

A gap does not mean:

• That no event occurred at that service
• That the service was down
• That the call failed

It means the SDK was not installed, or the SDK was not active on that path, or the events from that service were not available in the capture window.

When you see a gap, check whether the SDK is installed on the service that should appear there. If it is, check whether outbound header propagation is configured — the trace ID and parent CE ID headers must be forwarded on every downstream call.

Completeness labels

The artifact carries a completeness label that reflects how much of the causal chain is covered.

The label is topology-aware: a single gap in a 2-service trace is more significant than a single gap in a 20-service trace. The label accounts for this.

What full means: All causal links in the observed trace are connected. It does not mean every service in your fleet is instrumented — only that every link within this trace is accounted for.

What low means: The artifact is worth reading, but treat its conclusions with caution. Install the SDK on the services that appear as gaps.

First confirmed break

The "first confirmed break" is the earliest step in the causal chain where a non-success status was observed. This is where the investigation should begin.

It is reported as: {service_name} {operation} {status}. For example: payments HTTP_IN 503.

If no step in the trace has a non-success status, this field is absent. The incident may have been triggered by a latency alert rather than an error rate alert.

Affected services

The list of every distinct service observed in the trace. Services with gaps in the chain are not listed — only services that produced captured events. If you expect a service to appear but it does not, it either has no SDK installed or its events were not in the capture window.

What the artifact does not claim

The artifact will not tell you:

• Why a service failed (it only reports that it did)
• What would have happened if the chain were complete (no speculation about gap contents)
• That services not in the trace were unaffected (absence of evidence is not evidence of absence)
• Causation between steps that are not linked by explicit parent propagation

These limitations are intentional. The product's value is being reliable, not comprehensive. An artifact that speculates is less useful than one that only states what it knows.