How budgets and thresholds work

• Each project you protect has one budget: the most you want it to spend in a calendar month. It resets at the start of every month.
• The amount is in your billing account's currency, which Google fixes when the account is created, and in whole units (say $500, not $499.50).
• Spend is the project's actual cost so far this month, after credits such as the free trial or promotions. It is not a forecast.
• When you save, FireShield creates or updates a matching budget in your Google Cloud billing account, wired to report to FireShield. You can see it under Billing → Budgets & alerts in the Google Cloud console.

• A threshold is a percentage of the budget, from 1% to 100%. A budget can have up to 10, each at a different percentage.
• Each threshold carries the actions to run when spend reaches it:
  • Email alert (every plan).
  • Slack and Telegram alerts (Pro and Enterprise).
  • Soft Kill: a signed webhook asking your service to degrade itself. See the integration guide.
  • Hard Kill: disconnects the project's billing account. See what a Hard Kill is.
• A new budget starts with one threshold at 100% that emails you and runs a Hard Kill. Every threshold you add starts by emailing you, so none is silent by accident.

FireShield doesn't poll your project. Google publishes the budget's current spend several times a day, typically every half hour or so, and FireShield acts on each report as it arrives. Google's cost data lags real usage by up to several hours, so a report always describes spend from a little while ago.

On every report, FireShield divides the spend by the budget. Every threshold at or below that percentage is crossed, and each of its actions runs unless it already ran this month.

Example: a $500 budget with thresholds at 50%, 80% and 100%. A report of $430 is 86%, so the 50% and 80% thresholds are crossed. If the spend jumped there in one go, both run in that same update: nothing is skipped because a higher threshold was reached first.

When one update crosses a threshold with a Hard Kill, the Hard Kill runs before everything else, so the alerts sent with it can say whether billing was cut.

• Once per month. Google keeps reporting all month long, but an action that already ran this month isn't repeated.
• Changing the budget amount re-arms every action, so each one runs again when spend crosses its threshold of the new amount.
• A failed action is retried with every new report until it succeeds: an unreachable Soft Kill endpoint, a Slack channel that rejected the message, a Hard Kill that couldn't disconnect billing. Each attempt shows up in the project's Recent logs.
• A Slack or Telegram action on the Starter plan is skipped, not spent: if you upgrade before the month ends, it still runs.

Besides the threshold and the spend so far, every alert says whether the project is on track or ahead of pace for the month. Being on track means spend is no higher than the budget share of the days gone by. When it's ahead, the alert gives the date the budget runs out at the current rate. When it's on track or already over budget, it projects the month-end total. In the first two days of the month there is too little data, so the alert gives the verdict without a date or a projection.

The email also lists what the thresholds above will do, so you know whether a Hard Kill is coming next.

• The organization has no active FireShield subscription.
• The project is stopped by a Hard Kill. Monitoring resumes when you reactivate it.

• 50%: email, so you hear about a fast month early.
• 80%: email and Slack or Telegram, plus a Soft Kill if your service can degrade itself.
• 100%: email and a Hard Kill, the safety net.

Set the budget at the most you're willing to pay in a bad month, not at your usual spend, or the Hard Kill will take you offline on an ordinary busy day.