Guides
Alerts
Rules that watch your traffic and tell you when something crosses a line, on the dashboard and by webhook.
An alert rule watches one measure over a time window. When the measure crosses the threshold the rule fires: the event is recorded, it appears on the dashboard overview, and, if the rule has a webhook, a JSON message is sent to it.
#Kinds of rule
| Kind | Fires when | Threshold |
|---|---|---|
error_rate | The share of failed calls in the window is above the threshold | A fraction: 0.05 means 5% |
latency_p95_ms | The 95th-percentile latency in the window is above the threshold | Milliseconds |
spend_usd | Provider cost in the window is above the threshold | Dollars |
calls_below | The number of calls in the window is below the threshold | A count. Use it to notice a gateway that has gone quiet. |
A rule has a name, a window in seconds, an enabled switch, and an optional webhook.
#Creating one
In Alerts, or over the API:
curl -X POST "$RAKUVO_API_URL/v1/alerts/rules" \ -H "Authorization: Bearer $ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Too many failures", "kind": "error_rate", "threshold": 0.05, "window_seconds": 900, "webhook": "https://hooks.example.com/rakuvo", "enabled": true }'PUT /v1/alerts/rules/{id} updates a rule and DELETE removes it. GET /v1/alerts lists the times rules fired, each with the measured value, the threshold and a message.
#Webhooks
When a rule fires, Rakuvo sends one POST to the webhook URL with a JSON body containing text (a readable message, which Slack-style incoming webhooks display), rule, kind, value, threshold and time.
- The URL must be
https. - Webhooks cannot target private or internal addresses, so a rule cannot be used to make the control plane call into your network. Self-hosters testing locally can start the API with
-allow-private-webhooks. - The request times out after a few seconds. Treat the dashboard as the record and the webhook as a convenience, and do not rely on retries.
#Tuning
- Start with
error_rateat a few percent over 15 minutes and adjust once you know your normal. - Use a longer window for
spend_usdso one expensive call does not fire it. - A rule with a short window on a quiet agent will be noisy. Use a window long enough to contain a meaningful number of calls.