diff --git a/cmd/fanout-docgen/main.go b/cmd/fanout-docgen/main.go index e44974f98..021a2ddbd 100644 --- a/cmd/fanout-docgen/main.go +++ b/cmd/fanout-docgen/main.go @@ -229,7 +229,7 @@ func renderAlertEnv(vars []field) []byte { b.WriteString("---\n") b.WriteString(`title: "Alert expression variables"` + "\n") b.WriteString(`description: "Every value an alert rule expression can read, and what it means."` + "\n") - b.WriteString(`summary: "The variables available to an expr-lang alert rule, generated from the evaluation environment itself."` + "\n") + b.WriteString(`summary: "The variables available to a CEL alert rule, generated from the evaluation environment itself."` + "\n") b.WriteString("read_when:\n") b.WriteString(` - "You are writing an alert rule and need the variable names."` + "\n") b.WriteString(` - "A rule compiles but never fires, and you want to check what it is reading."` + "\n") @@ -239,10 +239,17 @@ func renderAlertEnv(vars []field) []byte { b.WriteString("{/* Generated by cmd/fanout-docgen from internal/alert. Edit the generator, not this page. */}\n\n") - b.WriteString("An alert rule's `expression` is [expr-lang](https://expr-lang.org) evaluated\n") + b.WriteString("An alert rule's `expression` is [CEL](https://cel.dev) evaluated\n") b.WriteString("against one service's rollup for the current window. These are the values it\n") - b.WriteString("can read — the names below are exactly what the evaluator binds, because both\n") - b.WriteString("this page and the evaluator come from the same struct.\n\n") + b.WriteString("can read — the names below match the variables declared and bound by the\n") + b.WriteString("evaluator.\n\n") + b.WriteString("Rules are type-checked against these declared variables when saved through the\n") + b.WriteString("API. Unknown variables, type mistakes, and non-boolean results are rejected\n") + b.WriteString("before the rule is saved.\n\n") + b.WriteString("Use CEL's standard operators and functions, such as `&&`, `||`, `!`, and\n") + b.WriteString("`service.startsWith(\"checkout\")`. Numeric variables are doubles; cross-type\n") + b.WriteString("numeric comparisons let you compare them with integer literals, as in\n") + b.WriteString("`error_rate > 0.02 && throughput > 10` or `p95 > 500`.\n\n") b.WriteString("| Variable | Type | Means |\n") b.WriteString("|---|---|---|\n") diff --git a/site/src/content/docs/guides/set-up-alerts.mdx b/site/src/content/docs/guides/set-up-alerts.mdx index eb877d156..157d453db 100644 --- a/site/src/content/docs/guides/set-up-alerts.mdx +++ b/site/src/content/docs/guides/set-up-alerts.mdx @@ -32,7 +32,7 @@ An expression, an optional service to scope it to, timing, and delivery: | Field | Means | |---|---| -| `expression` | The condition, in [expr-lang](https://expr-lang.org) | +| `expression` | The condition, in [CEL](https://cel.dev) | | `service` | Evaluate only for this service; omit for all | | `for_seconds` | How long the condition must hold before firing | | `cooldown_s` | Minimum quiet period after resolving before firing again | @@ -42,6 +42,10 @@ An expression, an optional service to scope it to, timing, and delivery: | `webhook_template` | Custom payload body; omit for the default | | `notify_on_resolve` | Also deliver when the alert clears | +When you create or replace a rule through the API, its expression is type-checked +against the declared variables and must return a boolean. An unknown variable or +a type mistake is rejected at save time. + ## Variables available to an expression An expression reads one service's rollup for the current window. The full list — @@ -53,7 +57,7 @@ evaluator actually binds. So a rule body reads like the thing it means: ```text -error_rate > 0.02 and throughput > 10 +error_rate > 0.02 && throughput > 10 ``` The throughput clause matters more than it looks. A service handling two diff --git a/site/src/content/docs/reference/alert-expressions.mdx b/site/src/content/docs/reference/alert-expressions.mdx index de3077b8c..364a73c11 100644 --- a/site/src/content/docs/reference/alert-expressions.mdx +++ b/site/src/content/docs/reference/alert-expressions.mdx @@ -1,7 +1,7 @@ --- title: "Alert expression variables" description: "Every value an alert rule expression can read, and what it means." -summary: "The variables available to an expr-lang alert rule, generated from the evaluation environment itself." +summary: "The variables available to a CEL alert rule, generated from the evaluation environment itself." read_when: - "You are writing an alert rule and need the variable names." - "A rule compiles but never fires, and you want to check what it is reading." @@ -11,10 +11,19 @@ generated: true {/* Generated by cmd/fanout-docgen from internal/alert. Edit the generator, not this page. */} -An alert rule's `expression` is [expr-lang](https://expr-lang.org) evaluated +An alert rule's `expression` is [CEL](https://cel.dev) evaluated against one service's rollup for the current window. These are the values it -can read — the names below are exactly what the evaluator binds, because both -this page and the evaluator come from the same struct. +can read — the names below match the variables declared and bound by the +evaluator. + +Rules are type-checked against these declared variables when saved through the +API. Unknown variables, type mistakes, and non-boolean results are rejected +before the rule is saved. + +Use CEL's standard operators and functions, such as `&&`, `||`, `!`, and +`service.startsWith("checkout")`. Numeric variables are doubles; cross-type +numeric comparisons let you compare them with integer literals, as in +`error_rate > 0.02 && throughput > 10` or `p95 > 500`. | Variable | Type | Means | |---|---|---|