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"
}
}Alert events and delivery jobs are committed durably before a webhook is sent.
Non-2xx responses and network failures are retried after
OPEN_SPANNER_ALERT_WORKER_RETRY_AFTER up to the configured maximum attempts.
Each attempt records its status code, duration, and error without changing the
immutable alert event.
Terminal failures remain visible in the dashboard and
GET /v1/alerts/delivery-jobs. After correcting the destination, retry one with
POST /v1/alerts/delivery-jobs/{id}/retry.
Worker Process
Alert evaluation and webhook delivery run outside the API process. Accepted usage first enters the transactional usage outbox; the usage worker durably queues matching alert work, and the alert worker evaluates rules and delivers their events.
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.