Thresholds

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 forecastedCopy Anchor Link

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.

LevelsCopy Anchor Link

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 sentCopy Anchor Link

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.

ExamplesCopy Anchor Link

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

[
  {"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.