# Thresholds

> Thresholds decide when a budget sends alerts, based on actual spending so far or on the forecast for the whole window.

A threshold is a rule that sends an alert when a budget's spending crosses a level. Every budget
has between one and ten thresholds, and each one alerts its own notification channels.

## Actual and forecasted

A threshold's `basis` decides what it compares:

* `actual` compares what the project has spent in the window so far. It reports something that
  has already happened, such as "80% of the budget is spent."
* `forecasted` compares what the whole window is projected to cost. It warns you early, while
  there is still time to act, such as "this month is on course to cost more than the budget."

The forecast assumes the rest of the window continues at the rate spent so far. For example, if a
project spends 250 in the first 7 days of a 31-day month, the forecast for the month is about
1107\. A forecast cannot know about resources you are about to add or remove.

Forecasted thresholds wait until a day of the window has passed, and report `unevaluated` until
then. A daily budget is too short to forecast, so it cannot have forecasted thresholds.

## Levels

A threshold's `unit` and `value` set the level:

* `percentage` is a share of the budget's amount. A value of `80` on a 1000 budget alerts at 800.
* `absolute` is an amount of money. A value of `1200` alerts at 1200, whatever the budget's amount.

`comparison` decides which side of the level alerts. The default, `greater_than_or_equal`, alerts
when spending reaches the level. `greater_than` alerts only once spending exceeds it. `less_than` and
`less_than_or_equal` alert when spending is below the level, which is useful for spotting a
service that has stopped running.

A threshold can also carry a `message`, which every alert includes, such as who to contact.

## When alerts are sent

A threshold is `ok` until spending crosses its level, then it moves to `alarm` and sends one alert
to each of its channels.

* An actual threshold alerts once per window. It stays quiet however far past the level spending
  goes, so add a second, higher threshold if you also want to hear about that.
* A forecasted threshold can alert again in the same window. If the forecast drops back below the
  level and later crosses it again, it sends a new alert.
* Every threshold starts again at `ok` in each new window.
* Turning a threshold or its budget off and on again in the same window does not send the alert a
  second time.
* Renaming a threshold starts it again, because Budgets tracks thresholds by name.

## Examples

These thresholds on a 1000 monthly budget cover the common cases:

```json
[
  {"name": "half", "basis": "actual", "unit": "percentage", "value": "50", "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
  {"name": "overrun-forecast", "basis": "forecasted", "unit": "percentage", "value": "100", "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
  {"name": "over", "basis": "actual", "unit": "percentage", "value": "100", "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f", "8b2d4f6a-1c3e-4a5b-9d7f-2e4c6a8b1d3f"]}
]
```

The first alerts when the month is half spent, the second warns early that it is heading over,
and the third alerts both channels when it has gone over.