Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions cmd/fanout-docgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand Down
8 changes: 6 additions & 2 deletions site/src/content/docs/guides/set-up-alerts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 —
Expand All @@ -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
Expand Down
17 changes: 13 additions & 4 deletions site/src/content/docs/reference/alert-expressions.mdx
Original file line number Diff line number Diff line change
@@ -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."
Expand All @@ -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 |
|---|---|---|
Expand Down
Loading