Skip to main content
This page explains the internals of Monigo’s usage alert system — how thresholds are evaluated, how duplicates are prevented, and how alerts reset across billing periods.

​
Evaluation Timing

Monigo uses two evaluation strategies depending on the alert type:
  • Real-time evaluation. usage_exceeded and wallet_balance_dropped alerts are checked each time a usage event is ingested or a wallet transaction is recorded. This means thresholds fire within seconds of the underlying value changing.
  • Periodic evaluation. cost_exceeded alerts are evaluated on a periodic schedule (typically every hour) because cost calculations depend on aggregated usage across an entire billing period. This avoids excessive computation while still providing timely notifications.

​
Threshold Deduplication

Each threshold within an alert fires at most once per billing period per subscription. Monigo tracks this using alert state records that store the threshold index and the billing period start date. If the same threshold is crossed multiple times within a period (for example, usage fluctuates around the boundary), only the first crossing triggers a notification. This deduplication is per-subscription, so a plan-level alert with 50 subscribers can fire up to 50 times per threshold per period — once for each subscriber that crosses the boundary.

​
Auto-Reset

At the start of each new billing period, all triggered alert states for that subscription are automatically reset to monitoring. This means:
  • Thresholds that fired in the previous period can fire again in the new period.
  • No manual intervention is required to “re-arm” alerts.
  • Historical triggered states are preserved for audit purposes — only the active tracking state is reset.
The reset is tied to the subscription’s billing cycle, not a calendar date. If a subscription bills on the 15th of each month, its alert states reset on the 15th.

​
Idempotency

Alert evaluation is idempotent. If the same event is ingested twice (for example, due to a retry), the alert engine checks the current state before firing. Since the state record already shows the threshold as triggered, no duplicate notification is sent. This extends to the acknowledgment flow: acknowledging an already-acknowledged alert is a no-op that returns success.

​
Plan-Level Inheritance

When an alert is scoped to a plan, Monigo automatically creates individual tracking states for each active subscription on that plan. This happens lazily — states are created when the alert is first evaluated for a given subscription, not when the alert is defined. If a new customer subscribes to the plan after the alert is created, they are picked up on the next evaluation cycle. If a subscription is canceled, its alert states are no longer evaluated but are retained for historical queries. This inheritance model means you define alerting rules once at the plan level and they apply uniformly to all subscribers without additional configuration.