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

# Metrics

> Learn what Xerg's top-level dollar metrics mean and how before and after deltas are computed.

Xerg reports economics in USD. Every audit summarizes current spend, confirmed waste, opportunity impact, and optional before and after deltas.

## Core audit metrics

### Total spend

The sum of all normalized call costs in the audit window.

### Observed spend

Spend taken directly from the telemetry source when a call already includes cost data.

### Estimated spend

Spend computed from token counts and Xerg's pricing catalog when observed cost is missing.

### Waste spend

The dollar impact of findings classified as confirmed `waste`.

Today that means:

* retry waste
* loop waste
* cache carryover for Cursor CSV audits when the billed pattern clears the waste bar

### Opportunity spend

The dollar impact of findings classified as `opportunity`.

Today that means:

* context outliers
* idle spend
* downgrade candidates
* max mode concentration for Cursor CSV audits when the billed mix is heavily premium

### Structural waste rate

```text theme={null}
wasteSpendUsd / totalSpendUsd
```

This is the conservative waste percentage used by `--fail-above-waste-rate`.

### Waste by signal source

Local audit summaries include `wasteBySignalSource`:

* `observedUsd`
* `inferredUsd`
* `declaredUsd`
* `unknownUsd`
* `inferredShare`

`unknownUsd` is used for older summaries that predate provenance fields. Xerg does not default missing provenance to observed.

## Breakdowns

Every audit includes spend breakdowns:

* by workflow
* by model

Each row includes:

* `spendUsd`
* `callCount`
* `observedShare`

`observedShare` tells you what fraction of that row's spend came from directly observed cost rather than estimation.

## Daily rollups

Every audit now includes:

* `spendByDay`
* `wasteByDay`

These series use UTC calendar days in `YYYY-MM-DD` format.

* `spendByDay` includes `spendUsd`, `observedSpendUsd`, `estimatedSpendUsd`, and `callCount`
* `wasteByDay` includes confirmed waste only
* `sum(spendByDay.spendUsd)` reconciles to `totalSpendUsd`
* `sum(wasteByDay.wasteUsd)` reconciles to `wasteSpendUsd`

## Compare metrics

When a compatible baseline exists and you run `xerg audit --compare`, Xerg adds:

* waste rate before and after
* waste per run before and after
* waste per 1k calls before and after
* inferred waste share before and after when provenance is available
* workload-dependent total spend delta
* workload-dependent structural waste delta
* delta run count
* delta call count
* top workflow swings
* top model swings
* high-confidence waste changes

The compare block leads with normalized rates and per-unit metrics so the before and after read survives workload changes. Absolute spend and waste deltas are still shown, but they are labeled workload-dependent because volume changes can affect them.

The push wire schema includes only the top-line comparison fields. The richer workflow, model, and finding-change details stay in the local summary.

## Cost per outcome

When runs carry outcome signals, audits include an outcomes rollup: success rate, cost per successful run, and spend on failed runs. Outcomes come from two places:

* observed terminal states: explicit success statuses, error or abort stop reasons
* declared outcomes: `xerg outcome --run <id>|--workflow <name> --status success|failure|partial|unknown`, stored locally and applied to future audits (declared outcomes override derived ones)

Runs with no outcome signal stay untracked rather than being guessed as successes. Token economics (cache read/write and reasoning tokens, cache spend) are rolled up alongside when the source reports them.

## Notes that always matter

* Cost per outcome requires outcome signals; audits without any outcome signal say so instead of showing numbers.
* Opportunity metrics are directional. They are worth testing, but they are not proven waste.
* Threshold gates only use confirmed structural waste, not opportunity impact.
* Detected source files with zero included calls are called out explicitly in a count-only extraction note instead of silently vanishing from the audit. Totals may understate real spend when that happens; use `xerg doctor --runtime <runtime> --verbose` locally to see which files (paths stay on your machine).