> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Define alerts (monitors) as config: threshold, event, and simulation triggers

An alert (monitor) reacts to a trigger by opening an issue and/or notifying Slack channels and webhooks. Pick one of three trigger types with `trigger.type`; the type is immutable once created (a change is delete-and-recreate).

## Threshold

Watch a metric aggregate over a rolling window. Opens an issue when it crosses the threshold, and optionally notifies Slack/webhooks. `metric` is the metric's slug (a custom metric you defined, or a Roark system metric); the variant defaults to the metric's default.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json
kind: alert
name: high-frustration
trigger:
  type: threshold
  metric: frustration_score      # metric slug (its metricId)
  aggregation: MEAN              # COUNT | RATE_PER_MINUTE | MEAN
  windowMinutes: 60
  operator: GT                   # GT | GTE | LT | LTE
  thresholdValue: 3
  minSampleSize: 5               # optional; skip windows with fewer data points
actions:
  slack:
    - channelId: C0123ABCXYZ     # Slack-native channel id
      channelName: '#agent-quality'
  webhooks:
    - https://hooks.example.com/roark/alerts
```

## Event

Fire on platform events (call/chat analysis, simulation jobs, metric collection, issues).

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json
kind: alert
name: analysis-failures
trigger:
  type: event
  events:
    - CALL_ANALYSIS_FAILED
    - CHAT_ANALYSIS_FAILED
actions:
  slack:
    - channelId: C0123ABCXYZ
      channelName: '#platform-alerts'
```

## Simulation

Notify on a simulation run-plan job outcome. `runPlan` (by name) scopes it to one run plan; omit for project-wide. A simulation alert requires exactly one Slack channel and does not support webhooks.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json
kind: alert
name: nightly-suite-result
trigger:
  type: simulation
  conditions: [FAILURE, THRESHOLD_FAILED]   # SUCCESS | FAILURE | THRESHOLD_FAILED
  runPlan: nightly-regression
  deliveryFormat: MESSAGE                    # MESSAGE | PDF
actions:
  slack:
    - channelId: C0999SIMS
      channelName: '#sim-results'
```

* **Threshold alerts always open an issue**; Slack and webhook delivery are optional additions.
* **Slack channels** are referenced by their Slack-native `channelId` (e.g. `C0123ABC`) plus a `channelName`. The Slack workspace is resolved from the project's connected Slack integration, so no UUIDs go in config.
* **Webhooks** must be public `http(s)` URLs.

<Note>
  Referencing a Slack channel requires a **Slack integration connected to the project** in Roark first. Connect Slack under the project's integration settings, then reference the channel by id here.
</Note>

<Note>
  For the full field reference of every kind, see the [Config DSL reference](https://schema.roark.ai/roark-config.schema.json) schema.
</Note>