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

KindFires whenThreshold
error_rateThe share of failed calls in the window is above the thresholdA fraction: 0.05 means 5%
latency_p95_msThe 95th-percentile latency in the window is above the thresholdMilliseconds
spend_usdProvider cost in the window is above the thresholdDollars
calls_belowThe number of calls in the window is below the thresholdA 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:

bash
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_rate at a few percent over 15 minutes and adjust once you know your normal.
  • Use a longer window for spend_usd so 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.