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, Alert Rules, Alert Channels, and Alert History.

Alert rules reference governance scopes and budgets by ID. Define the referenced virtual keys, teams, customers, budgets, and rate limits under 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.

{
  "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

{
  "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.

{
  "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

# Any budget in the scope reaches 80%
budget_usage_percent >= 80.0

# Absolute spend crosses $100
budget_spent > 100.0

# Request rate limit reaches 90%
rate_limit_request_usage_percent >= 90.0

# 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.

---

Specific budget example

Use target_type: "budget" and target_id when a rule should evaluate one budget instead of every budget in the scope.

{
  "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.

{
  "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.

---

Validation

Add the schema URL to get editor autocomplete and validation:

{
  "$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

Alerting overview

Learn how alert evaluation, cooldowns, history, and clustering work.

Governance config

Define the virtual keys, teams, customers, budgets, and rate limits that alert rules evaluate.