Alerts
Watch usage windows against thresholds.
Alerts let Open Spanner watch a meter for threshold crossings. A rule selects a meter, an optional subject, optional dimension filters, a time window, a comparator, and a delivery destination.
For example, an alert can watch api_requests for one endpoint and trigger when the last hour reaches 10,000 requests.
How Alerts Work
An alert rule evaluates the meter's aggregation over a rolling window:
| Field | Meaning |
|---|---|
| Meter | The usage signal to evaluate. |
| Subject | Optional subject filter, such as one customer or organization. |
| Metadata | Optional dimension filters, such as endpoint=/checkout or plan=enterprise. |
| Window | How far back the rule looks during evaluation. |
| Comparator | gt, gte, lt, lte, eq, or neq. |
| Threshold | The value to compare against. |
| Evaluation interval | How often the rule should be checked when no new matching usage arrives. |
| Destination | The notification target to use when alert state changes. The first supported destination type is webhook. |
When usage is reported, Open Spanner finds enabled rules for that meter and only queues rules whose subject and metadata filters match the event. This keeps alert evaluation tied to the relevant usage stream instead of scanning every rule for every event.
States And Events
Each rule has a current state:
| State | Meaning |
|---|---|
ok | The current window is within the configured threshold. |
alerting | The current window crosses the threshold. |
no_data | No retained usage matched the rule window. |
error | The last evaluation failed. |
Open Spanner records alert events when a rule first enters alerting, resolves back out of alerting, or fails evaluation.
Destinations And Webhooks
Alert destinations hold the webhook URL and signing secret. Rules reference a destination, so multiple thresholds can notify the same endpoint without copying secrets into each rule.
For webhook destinations, the alert worker sends an HTTP POST when a rule creates a triggered or resolved event. The dashboard shows the signing secret only when a destination is created or rotated.
Webhook requests include:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | open-spanner-alert-worker |
X-Open-Spanner-Timestamp | Unix timestamp used for signing. |
X-Open-Spanner-Signature | v1=<hex-encoded-hmac-sha256> when the destination has a signing secret. |
The signature is computed over:
<timestamp>.<raw_request_body>Use the destination signing secret to verify the HMAC before trusting the webhook payload.
The webhook payload includes the rule, current state, and event:
{
"rule": {
"id": "rule_123",
"name": "High API traffic",
"meter": "api_requests",
"window_seconds": 3600,
"comparator": "gte",
"threshold": 10000,
"destination_id": "dest_123",
"destination_name": "Primary webhook"
},
"state": {
"status": "alerting",
"value": 12840,
"message": "value 12840.0000 gte threshold 10000.0000",
"evaluated_at": "2026-06-18T20:00:00Z"
},
"event": {
"id": "event_123",
"rule_id": "rule_123",
"type": "triggered",
"value": 12840,
"message": "value 12840.0000 gte threshold 10000.0000",
"created_at": "2026-06-18T20:00:00Z"
}
}Webhook delivery is best-effort in this version. A failed webhook is logged by the worker; the alert state and alert event are still recorded in Open Spanner.
Worker Process
Alert evaluation runs outside the API process. The API records usage and queues alert work; the alert worker claims queued jobs from the same database and evaluates them.
Run at least one alert worker when alerts are enabled. With Postgres, multiple alert workers can run at the same time because jobs are claimed with row-level locking.
Current Scope
Alerts are visible in the dashboard and full REST API. They are intentionally not part of the generated SDK surface, which stays focused on meters, usage ingestion, querying, and direct exports.