Create or update an alert rule for the calling tenant in one call. WRITE: available to any authenticated user. Omit ruleId to create a new rule; supply ruleId to REPLACE an existing one.

UPDATE IS A WHOLE-OBJECT REPLACE, NOT A MERGE. Every field you leave out is cleared — omitting description sets it to null. To change one thing, fetch the rule with get_alert_rules and re-send its full spec with that one field altered. Two things are carved out and survive omission: status — ACTIVE/DISABLED is preserved; change it with set_alert_rule_status delivery — notifyOnResolve is preserved. Where a rule's alerts go is not part of the rule spec: change it with set_alert_rule_destinations, and read it with get_alert_rule_destinations.

channelIds applies on CREATE only (ADMIN only): the new rule's notification destinations as registry channel UUIDs from the investigation service's list_alert_channels. Omit to inherit the tenant's alerting default; pass [] to create the rule with its alerts off. Sending channelIds together with ruleId is rejected in problems[]; use set_alert_rule_destinations to change an existing rule's destinations.

Re-validates exactly like preview_alert_rule: if the spec is invalid, nothing is persisted and problems[] is populated instead of rule — preview_alert_rule first to calibrate the threshold, then save once problems[] is empty there.

The rule still saves even when warnings[] is non-empty — warnings are advisory, never a reason to withhold saving, unlike problems[]. warnings[] currently carries one code, FIELD_NEVER_OBSERVED: a filter/groupBy field querysql couldn't resolve to a known column (so it silently falls back to reading it from the JSON catch-all) and that has never appeared in this customer's recent telemetry — almost always a typo'd field name, especially when preview_alert_rule also reported dataCoverage.status = NO_MATCHING_DATA. Fix the spelling and re-preview rather than treat it as a calibration problem.

Authors a single metric or anomaly rule (one measure over a rolling window). Compound multi-condition rules can't be created here — build those in the web editor.

METRIC RULE (structured) — watches one measure over a rolling time window: source: telemetry source (required): LOGS, SPANS, METRICS filter: optional QuerySQL boolean filter, e.g. service = 'my-svc' fn: catalog measure function, e.g. count, error_rate, p95, error_burn_rate arg: optional field the measure operates on, e.g. duration_ms for p95 params: optional named measure params, e.g. {"budget":"0.001"} (error_burn_rate) expression: optional free-form aggregate (used instead of fn) — a ratio/calculation, e.g. countIf(status_code = 'ERROR') * 100.0 / count() (this is exactly fn: error_rate; use fn instead unless you need a custom ratio — both already return 0-100, don't divide by 100 again) metricName/metricType: required only when source is METRICS unit: optional explicit display unit for the measure, e.g. BYTES or DURATION_MS — set it when the metric name doesn't self-describe its unit (OTel names like jvm.memory.used or http.server.request.duration carry no unit suffix); omit it to let the server infer the unit from the metric name or measure function windowMinutes: rolling window length in minutes (required) groupBy: optional list of plain field names to group the series by, e.g. service. Field names only: a string that looks like an expression (it contains a parenthesis or a space) is rejected in problems[], because the rule page and the alert title would then show the raw expression as the group name. derivedGroupBy: optional list of computed group keys, each an object {"expression": "...", "label": "..."}, e.g. {"expression": "regexp_extract(message, 'customerId=([0-9a-f-]+)', 1)", "label": "customer"}. Both fields are required and non-blank. The label is what rule pages and alert titles show, so give it a short readable name. groupBy and derivedGroupBy can be used together. comparator: threshold comparator: GT, GTE, LT, LTE (required for static) warningThreshold: the warning-tier threshold the measure is compared against (required for static) warningConsecutiveWindows: consecutive breaching windows for the warning tier (default 1) criticalThreshold / criticalConsecutiveWindows: optional escalation tier

ANOMALY METRIC (structured) — flags a measure that deviates from its own historical baseline instead of a fixed threshold. Supply zScoreThreshold + direction instead of comparator/warningThreshold; groupBy must be empty. zScoreThreshold: robust z-score magnitude that counts as anomalous (> 0) direction: HIGH (spikes above baseline) or LOW (drops below baseline) anomalyConsecutiveWindows: consecutive anomalous windows required (>= 1)

Common fields: name: human-readable rule name (required, non-blank) description: optional; shown with every alert this rule raises, read during triage. One or two short sentences: what the breach means for users, then the first thing to check. E.g. "Search is slow for users. Check the search-index cluster first." Leave out backtest or backfill numbers, calibration history, incident history, dates and runbook steps. notifyOnResolve: whether to notify when the alert resolves (default true) active: create-only — whether the rule starts ACTIVE (default true) or DISABLED