> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Alerting
> Configure Bifrost Enterprise alert channels, rules, evaluation frequency, history retention, and webhook network controls in config.json
Alerting is an **enterprise-only** feature and requires the enterprise Bifrost image.
The `alerting` block lets you seed alert channels and CEL-based alert rules directly in `config.json`. Rules evaluate governance metrics, such as budget usage and rate limit usage, and send notifications to Slack, Microsoft Teams, PagerDuty, or generic webhooks.
Use this page when you want alerting to be managed as code. For the UI workflow and runtime concepts, see [Alerting](/enterprise/alerting/overview), [Alert Rules](/enterprise/alerting/alert-rules), [Alert Channels](/enterprise/alerting/alert-channels), and [Alert History](/enterprise/alerting/alert-history).
Alert rules reference governance scopes and budgets by ID. Define the referenced virtual keys, teams, customers, budgets, and rate limits under [`governance`](/deployment-guides/config-json/governance), or create them through the Web UI or API before the rule is evaluated.
***
## Quick example
This example creates one Slack channel, one generic webhook channel, and two rules: one budget alert for a virtual key and one request-rate-limit alert for a team.
```json theme={null}
{
"alerting": {
"history_retention_days": 365,
"evaluation_interval_seconds": 10,
"webhook_network": {
"allow_http": false,
"allow_private_network": false
},
"channels": [
{
"id": "slack-platform",
"name": "Platform Slack",
"type": "slack",
"enabled": true,
"config": {
"webhook_url": "env.SLACK_WEBHOOK_URL"
},
"cooldown_seconds": 60
},
{
"id": "ops-webhook",
"name": "Ops webhook",
"type": "webhook",
"enabled": true,
"config": {
"url": "env.ALERT_WEBHOOK_URL",
"headers": {
"X-Alert-Token": "env.ALERT_WEBHOOK_TOKEN"
}
}
}
],
"rules": [
{
"id": "vk-budget-80",
"name": "Virtual key budget at 80%",
"enabled": true,
"scope_type": "virtual_key",
"scope_id": "vk-platform",
"cel_expression": "budget_usage_percent >= 80.0",
"channel_ids": ["slack-platform"],
"cooldown_seconds": 300
},
{
"id": "team-requests-90",
"name": "Team request limit at 90%",
"enabled": true,
"scope_type": "team",
"scope_id": "team-platform",
"cel_expression": "rate_limit_request_usage_percent >= 90.0",
"channel_ids": ["slack-platform", "ops-webhook"],
"notify_once_per_reset_cycle": true
}
]
}
}
```
***
## Top-level fields
| Field | Type | Default | Description |
| ----------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `history_retention_days` | integer | `365` | Days to retain alert history. Set `0` to disable retention pruning. |
| `evaluation_interval_seconds` | integer | `60` | Seconds between rule evaluations. Use `5` to `10` for one-minute budget or rate-limit reset windows. |
| `webhook_network` | object | See below | Outbound URL validation controls for webhook-based channels. |
| `channels` | array | `[]` | Declarative notification destinations. |
| `rules` | array | `[]` | Declarative CEL rules evaluated against governance metrics. |
Alerting samples the current governance counters at this interval. Keep `evaluation_interval_seconds` comfortably below the shortest configured budget or rate-limit reset duration so a brief threshold breach is observed before governance resets the counter.
### Webhook network controls
```json theme={null}
{
"alerting": {
"webhook_network": {
"allow_http": false,
"allow_private_network": false
}
}
}
```
| Field | Default | Description |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `allow_http` | `false` | Allow Slack, Microsoft Teams, and generic webhook channels to use `http://` URLs. PagerDuty always uses its fixed HTTPS endpoint. |
| `allow_private_network` | `false` | Allow webhook destinations on RFC1918 private networks. Link-local and unspecified addresses remain blocked. |
Keep both webhook network controls disabled for production unless you are intentionally sending alerts to trusted internal endpoints. Enabling them weakens TLS and SSRF protections.
***
## Channels
Each channel needs a stable `id`, a display `name`, a `type`, an `enabled` flag, and a type-specific `config`.
| Field | Required | Description |
| ------------------ | ----------- | -------------------------------------------------------------------------------------- |
| `id` | Yes | Stable channel ID. Rules reference this ID in `channel_ids`. |
| `name` | Yes | Operator-facing channel name. |
| `description` | No | Optional description. |
| `type` | Yes | `slack`, `microsoft_teams`, `pagerduty`, or `webhook`. |
| `enabled` | Yes | Whether this channel can receive notifications. |
| `cooldown_seconds` | No | Minimum seconds between sends for this channel. Set `0` for no channel-level cooldown. |
| `config` | Conditional | Required for every supported channel type. |
### Channel config
Credential and endpoint fields support `env.VAR_NAME` references. Bifrost resolves the value from the process environment at startup.
| Channel type | Required config | Notes |
| ----------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
| `slack` | Exactly one of `webhook_url` or `url` | Slack incoming webhook URL. |
| `microsoft_teams` | Exactly one of `webhook_url` or `url` | Teams incoming webhook or Workflows URL. |
| `pagerduty` | Exactly one of `routing_key` or `integration_key` | PagerDuty Events API v2 integration key. |
| `webhook` | Exactly one of `url` or `webhook_url` | Generic webhook URL. Optional `headers` values also support `env.VAR_NAME`. |
For each alias pair, provide exactly one key. For example, use either `webhook_url` or `url` for Slack, not both.
```json theme={null}
{
"alerting": {
"channels": [
{
"id": "teams-ops",
"name": "Ops Teams",
"type": "microsoft_teams",
"enabled": true,
"config": {
"webhook_url": "env.TEAMS_WEBHOOK_URL"
}
},
{
"id": "pagerduty-prod",
"name": "Production PagerDuty",
"type": "pagerduty",
"enabled": true,
"config": {
"routing_key": "env.PAGERDUTY_ROUTING_KEY"
}
}
]
}
}
```
***
## Rules
Rules evaluate CEL expressions against governance metrics collected for a virtual key, team, or customer.
| Field | Required | Description |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `id` | Yes | Stable rule ID. |
| `name` | Yes | Operator-facing rule name. |
| `description` | No | Optional description. |
| `enabled` | Yes | Whether this rule is evaluated. |
| `scope_type` | Yes | `virtual_key`, `team`, or `customer`. |
| `scope_id` | Yes | ID of the scoped virtual key, team, or customer. |
| `cel_expression` | Yes | CEL expression that evaluates to a boolean. |
| `query` | No | Optional UI query-builder representation of `cel_expression`. |
| `cooldown_seconds` | No | Minimum seconds between notifications for this rule. Default is `60`. Set `0` to disable rule-level cooldown. |
| `notify_once_per_reset_cycle` | No | When `true`, notify at most once per matched budget or rate-limit reset cycle. |
| `channel_ids` | Yes | One or more alert channel IDs. |
| `target_type` | Conditional | Use `budget` with `target_id` to evaluate one specific budget. |
| `target_id` | Conditional | Required when `target_type` is set. |
### Scopes and targets
Every rule must have a scope. A rule can either evaluate all budgets for that scope or target one budget explicitly.
| Behavior | `target_type` | `target_id` |
| --------------------------------- | ------------- | ----------- |
| Evaluate all budgets in the scope | Omit | Omit |
| Evaluate one budget | `budget` | Budget ID |
`target_type` and `target_id` must be provided together.
### CEL examples
```python theme={null}
# Any budget in the scope reaches 80%
budget_usage_percent >= 80.0
```
```python theme={null}
# Absolute spend crosses $100
budget_spent > 100.0
```
```python theme={null}
# Request rate limit reaches 90%
rate_limit_request_usage_percent >= 90.0
```
```python theme={null}
# Either budget or token rate limit is exhausted
budget_usage_percent >= 100.0 || rate_limit_token_usage_percent >= 100.0
```
For the complete variable list, see [Alerting CEL variables](/enterprise/alerting/overview#cel-variables).
***
## Specific budget example
Use `target_type: "budget"` and `target_id` when a rule should evaluate one budget instead of every budget in the scope.
```json theme={null}
{
"alerting": {
"rules": [
{
"id": "vk-platform-monthly-budget-90",
"name": "Platform monthly budget at 90%",
"enabled": true,
"scope_type": "virtual_key",
"scope_id": "vk-platform",
"target_type": "budget",
"target_id": "budget-platform-monthly",
"cel_expression": "budget_usage_percent >= 90.0",
"channel_ids": ["pagerduty-prod"],
"cooldown_seconds": 600
}
]
}
}
```
***
## Reset-cycle notifications
Set `notify_once_per_reset_cycle` when you want one notification per budget or rate-limit reset window, instead of repeated sends based on a cooldown.
```json theme={null}
{
"alerting": {
"rules": [
{
"id": "team-token-limit-cycle",
"name": "Team token limit per reset cycle",
"enabled": true,
"scope_type": "team",
"scope_id": "team-platform",
"cel_expression": "rate_limit_token_usage_percent >= 90.0",
"channel_ids": ["slack-platform"],
"notify_once_per_reset_cycle": true
}
]
}
}
```
This is useful for rate limits and recurring budgets because the same condition can remain true until the reset window rolls over.
***
## Clusters
In a Bifrost Enterprise cluster, only the leader evaluates alert rules and writes alert history. Followers can serve inference traffic and update shared governance usage, but they do not dispatch duplicate alerts.
No extra alerting configuration is required for cluster mode. Configure clustering separately under [`cluster_config`](/deployment-guides/config-json/cluster).
***
## Validation
Add the schema URL to get editor autocomplete and validation:
```json theme={null}
{
"$schema": "https://www.getbifrost.ai/schema"
}
```
The schema validates the channel type, required channel config, rule scopes, required `channel_ids`, and the `target_type` / `target_id` pairing.
***
## Next steps
Learn how alert evaluation, cooldowns, history, and clustering work.
Define the virtual keys, teams, customers, budgets, and rate limits that alert rules evaluate.