> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Drift Monitor

> Distribution-level monitoring across five metrics, with composite scoring and timeline charts.

Aggregate dashboards catch the obvious. Drift Monitor catches the slow, distributional changes that aggregate charts miss — a small but steady increase in tool-call retries, a quiet shift in response length, a gradually rising refusal rate.

***

## What "drift" means here

Drift Monitor compares the distribution of a metric in a recent window against a baseline distribution. When the shape of the distribution moves enough, it's flagged. The composite drift score combines movement across all five tracked metrics.

```mermaid theme={"system"}
flowchart LR
    Baseline[Baseline window] --> Compare{"Distribution<br/>comparison"}
    Recent[Recent window] --> Compare
    Compare --> Metric[Per-metric score]
    Metric --> Composite[Composite score]
    Composite --> Alert{Above threshold?}
    Alert -->|Yes| Notify[Drift event]
    Alert -->|No| Sleep[No-op]
```

***

## The five metrics

| Metric                         | What it captures                         |
| ------------------------------ | ---------------------------------------- |
| **Latency distribution**       | Wall-clock duration of each call.        |
| **Token-count distribution**   | Total tokens (input + output) per call.  |
| **Cost distribution**          | Cost per call.                           |
| **Error rate**                 | Share of errored calls in the window.    |
| **Output-length distribution** | Character or token count of completions. |

Each contributes to the composite score with a configurable weight.

***

## Running a drift check

Drift snapshots can run on a schedule or be triggered ad hoc through the API.

```http theme={"system"}
POST /api/drift/compute
{
  "app_id": "...",
  "baseline_window": { "days": 30 },
  "recent_window": { "days": 7 }
}
```

Each computation produces a `DriftSnapshot` and one `DriftResult` per metric. The snapshot powers the timeline chart; the per-metric results power the distribution histograms.

***

## Reading the results

<Steps>
  <Step title="Open the timeline">
    The timeline plots the composite score over time. Spikes are the moments worth investigating.
  </Step>

  <Step title="Drill into one snapshot">
    Click a snapshot. The detail view splits the score into the five per-metric contributions.
  </Step>

  <Step title="Compare distributions">
    For each metric, the histogram overlays the baseline and recent distributions so the shift is visible.
  </Step>

  <Step title="Jump to the runs">
    From the snapshot detail, link out to the affected runs in [LLM Calls](./llm-calls) for ground-truth inspection.
  </Step>
</Steps>

***

## When to wire drift in

<CardGroup cols={2}>
  <Card title="After a model swap" icon="repeat">
    Compare 7 days before vs 7 days after to confirm the new model behaves consistently.
  </Card>

  <Card title="After a prompt change" icon="pen-to-square">
    Use the deployment timestamp as the boundary between baseline and recent.
  </Card>

  <Card title="As a regression backstop" icon="shield-halved">
    Schedule daily drift checks against a 30-day baseline. Spikes flag silent regressions.
  </Card>

  <Card title="Before regulatory reviews" icon="clipboard-check">
    Auditors care about stability. Drift evidence is one of the artefacts they ask for.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Alerts" icon="bell" href="./alerts">
    Trigger alerts when the composite score breaches a threshold.
  </Card>

  <Card title="Compliance heatmap" icon="grid" href="../compliance/gap-analysis-heatmap">
    Drift evidence feeds into the operational-control views.
  </Card>
</CardGroup>