Skip to main content

Causal Anomaly Detection (CIAD)

Causal Anomaly Detection is InfraSage's early-warning system. Ordinary anomaly detection asks "is this signal unusual?". CIAD asks a different question: "have the relationships between this service's signals broken down?"

Incidents rarely begin with one metric crossing a line. They often begin with a structural shift: throughput stops predicting latency, or database health stops predicting the error rate, while every individual metric still looks normal. CIAD watches for those breakdowns, which can give you minutes of warning before an incident is visible anywhere else.

How it works, in outline​

InfraSage learns which of a service's signals drive which others, and how strongly: traffic and latency, latency and errors, database health and response time, queue depth and throughput, errors and fatal logs. Some of these relationships hold for almost any service and are active from the first day. Others are learned from your own fleet once there is enough history, and over time they replace the generic ones with relationships that fit your systems.

Every few minutes each service gets a causal score from 0 to 1: how much of the structure it normally has is currently missing. When enough of it breaks down, the service is flagged Pre-Fault.

A pre-fault flag on its own is an early warning to look, not a page. When a pre-fault service then also shows an ordinary anomaly, the two together are a strong signal.

When it starts working​

  • Built-in relationships apply from day one.
  • Fleet-learned relationships need about two weeks of history across at least ten services. Discovery then runs nightly, and you can trigger it by hand.

Viewing CIAD results​

In the console​

  • The Causal Detection page lists the relationships InfraSage has learned and how widely each holds across your fleet, and every service's current score, highest first, with Pre-Fault badges. Trigger Discovery starts fleet discovery by hand.
  • Incident panels show an amber ⚡ Causal Pre-Fault banner when the flag is active.
  • Each Service Detail page charts the service's causal score over the last two hours.

Via the API​

# Latest causal scores (all services)
curl $INFRASAGE_URL/api/v1/ciad/scores \
  -H "Authorization: Bearer $TOKEN"

# Historical scores for one service (last 60 min)
curl "$INFRASAGE_URL/api/v1/services/payment-api/causal-history?minutes=60" \
  -H "Authorization: Bearer $TOKEN"

# Trigger fleet discovery manually (async, returns 202)
curl -X POST $INFRASAGE_URL/api/v1/ciad/discover \
  -H "Authorization: Bearer $TOKEN"

Example score:

{
  "service_id": "payment-api",
  "window_timestamp": "2026-05-09T04:28:00Z",
  "causal_score": 0.61,
  "pre_fault": true
}

Relationship to anomaly detection​

CIAD and anomaly detection are independent. Neither changes the other's results.

Anomaly detectionCIAD
QuestionIs a signal unusual?Has the structure between signals broken?
Typical leadWhen the symptom appearsOften minutes before
ResultAlert with severityPre-Fault flag and score
Cold startAbout a day of historyBuilt-in relationships at once; fleet-learned ones after about two weeks

If CIAD is disabled, its endpoints return {"error":"ciad_disabled"} with HTTP 503. Anomaly detection and telemetry quality scoring carry on as normal.