Working with Burn Alerts¶

Burn alerts notify you when you're consuming your SLO error budget too quickly. They help prevent budget exhaustion before it impacts your SLO compliance.

Understanding Burn Alerts¶

Burn alerts work with SLOs to provide early warning when error budgets are depleting faster than expected. Two alert types are available:

Exhaustion Time: Alerts when budget will be exhausted within X minutes
Budget Rate: Alerts when budget drops by X% within a time window

Basic Burn Alert Operations¶

List Burn Alerts for an SLO¶

async def list_burn_alerts(
    client: HoneycombClient, dataset: str, slo_id: str
) -> list[BurnAlert]:
    """List all burn alerts for an SLO.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the SLO
        slo_id: ID of the SLO

    Returns:
        List of burn alerts
    """
    alerts = await client.burn_alerts.list_async(dataset, slo_id=slo_id)
    for alert in alerts:
        print(f"{alert.alert_type}: {alert.description}")
    return alerts

Get a Specific Burn Alert¶

async def get_burn_alert(
    client: HoneycombClient, dataset: str, alert_id: str
) -> BurnAlert:
    """Get a specific burn alert.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the alert
        alert_id: ID of the burn alert

    Returns:
        The burn alert object
    """
    alert = await client.burn_alerts.get_async(dataset, alert_id)
    print(f"Type: {alert.alert_type}")
    print(f"Description: {alert.description}")
    print(f"Triggered: {alert.triggered}")
    return alert

Update a Burn Alert¶

async def update_burn_alert(
    client: HoneycombClient, dataset: str, alert_id: str, recipient_id: str
) -> BurnAlert:
    """Update a burn alert's parameters.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the alert
        alert_id: ID of the burn alert to update
        recipient_id: ID of the recipient to notify

    Returns:
        The updated burn alert
    """
    # Get existing alert first to preserve values
    existing = await client.burn_alerts.get_async(dataset, alert_id)

    # Update with new values
    updated = await client.burn_alerts.update_async(
        dataset,
        alert_id,
        BurnAlertCreate(
            alert_type=existing.alert_type,
            slo={"id": existing.slo.id} if existing.slo else {"id": ""},
            description="Updated: Alert when budget depletes within 1 hour",
            exhaustion_minutes=60,  # Change from 120 to 60 minutes
            recipients=[BurnAlertRecipient(id=recipient_id)],
        ),
    )
    return updated

Delete a Burn Alert¶

async def delete_burn_alert(
    client: HoneycombClient, dataset: str, alert_id: str
) -> None:
    """Delete a burn alert.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the alert
        alert_id: ID of the burn alert to delete
    """
    await client.burn_alerts.delete_async(dataset, alert_id)

Creating Burn Alerts¶

Exhaustion Time Alert¶

Alert when budget will be exhausted within a specified time:

async def create_exhaustion_time_alert(
    client: HoneycombClient, dataset: str, slo_id: str, recipient_id: str
) -> str:
    """Create a burn alert that triggers when budget will exhaust within time.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the SLO
        slo_id: ID of the SLO to monitor
        recipient_id: ID of the recipient to notify

    Returns:
        The created burn alert ID
    """
    alert = await client.burn_alerts.create_async(
        dataset,
        BurnAlertCreate(
            alert_type=BurnAlertType.EXHAUSTION_TIME,
            slo={"id": slo_id},
            description="Alert when budget depletes within 2 hours",
            exhaustion_minutes=120,
            recipients=[BurnAlertRecipient(id=recipient_id)],
        ),
    )
    return alert.id

Budget Rate Alert¶

Alert when budget drops by a percentage within a time window:

async def create_budget_rate_alert(
    client: HoneycombClient, dataset: str, slo_id: str, recipient_id: str
) -> str:
    """Create a burn alert that triggers on rapid budget consumption.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the SLO
        slo_id: ID of the SLO to monitor
        recipient_id: ID of the recipient to notify

    Returns:
        The created burn alert ID
    """
    alert = await client.burn_alerts.create_async(
        dataset,
        BurnAlertCreate(
            alert_type=BurnAlertType.BUDGET_RATE,
            slo={"id": slo_id},
            description="Alert on rapid budget consumption",
            budget_rate_window_minutes=60,
            budget_rate_decrease_threshold_per_million=10000,  # 1% drop
            recipients=[BurnAlertRecipient(id=recipient_id)],
        ),
    )
    return alert.id

Alert Type Comparison¶

Alert Type	Use When	Configuration
Exhaustion Time	You want to know when budget will run out	`exhaustion_minutes` - time until budget exhaustion
Budget Rate	You want to catch sudden spikes in errors	`budget_rate_window_minutes` + `budget_rate_decrease_threshold_per_million`

Understanding Budget Rate Thresholds¶

The budget_rate_decrease_threshold_per_million is expressed as parts per million:

10000 = 1% budget drop (10,000 / 1,000,000)
5000 = 0.5% budget drop (5,000 / 1,000,000)

Best Practice: Layer alerts with multiple thresholds (critical at 2 hours, warning at 24 hours). Combine both exhaustion time and budget rate alerts for comprehensive coverage.

Sync Usage¶

All burn alert operations have sync equivalents:

with HoneycombClient(api_key="...", sync=True) as client:
    # List burn alerts for SLO
    alerts = client.burn_alerts.list("my-dataset", slo_id="slo-123")

    # Create burn alert (requires recipient_id)
    alert = client.burn_alerts.create(
        "my-dataset",
        BurnAlertCreate(
            alert_type=BurnAlertType.EXHAUSTION_TIME,
            slo_id="slo-123",
            exhaustion_minutes=120,
            recipients=[BurnAlertRecipient(id=recipient_id)]
        )
    )

    # Get, update, delete burn alert
    alert = client.burn_alerts.get("my-dataset", alert_id)
    updated = client.burn_alerts.update("my-dataset", alert_id, BurnAlertCreate(...))
    client.burn_alerts.delete("my-dataset", alert_id)