Burn Alerts API

This feature is available as part of the Honeycomb Pro and Enterprise plans.

Honeycomb Burn Alerts warn when your SLO budget will be exhausted in a certain amount of time. This page contains information on creating and managing Burn Alerts via API.

Defining a Burn Alert requires a Honeycomb Service Level Objective (SLO) as a pre-requisite. Create and manage SLOs via the Honeycomb UI or via API.

Authorization and Headers

The only expected header is X-Honeycomb-Team, which is your API key, and it is required. The API key must have the Manage SLOs permission. Learn more about API keys.

Fields on a Burn Alert for an SLO

A Burn Alert consists of:

exhaustion_minutes: (required) (int) amount of time in minutes left before SLO is exhausted. The alert will fire when this exhaustion threshold is reached
slo: (required) (object) details about the SLO associated with the burn alert
- id: (required) (string) SLO ID
recipients: (required) a list of Recipients to notify when an alert fires.

Recipients can be created and managed via the Recipients API. To use an existing recipient, it is recommended to specify the recipient by ID. The type and target are NOT required when specifying the Recipient ID.

Specifying Recipients

Recipients can be created and managed via the Recipients API.

To use existing recipients with your triggers, it is best to specify the recipient using the recipient’s unique ID. There are a few options to get a recipient’s ID via an API:

Use the Recipients GET ALL endpoint
Run the Get Burn Alert
Run the List Triggers or Get Trigger API to get the JSON output for the trigger.

If a recipient is passed with only the type and target included but no ID, Honeycomb will make a best effort to match to an existing recipient. If specifying by type and target, type must be one of the following values: email, slack, pagerduty, or webhook.

PagerDuty recipients can also include a details object with a pagerduty_severity attribute. Valid severity values are critical, error, warning, or info. If pagerduty_severity is not included, the severity will default to critical.

Create a Burn Alert

A burn alert for an SLO can be created by sending a POST request to /1/burn_alerts/<dataset>. The Alert for the SLO will be created against the dataset and within the environment associated with your API key.

The body of the POST should be a JSON encoded object containing key/value pairs. ID cannot not be set during creation.

A successful response will return HTTP 201. Invalid input will result in a HTTP 422 being returned.

Create Example Request

In the below examples, recipient ID and type/target are included to show the parameters available when using the API. In practice, Honeycomb will use the recipient ID parameter first, if available, to match recipients before trying other parameters. For more information, see Specifying Recipients.

Create Example Request: Email Recipient

curl https://api.honeycomb.io/1/burn_alerts/<dataset> -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "exhaustion_minutes": 120,
    "recipients": [
        {
        "id": "abcd123",
        "type":"email",
        "target":"alerts@example.com"
        }
    ]
}
'

Create Example Request: Slack Recipient

curl https://api.honeycomb.io/1/burn_alerts/<dataset> -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "exhaustion_minutes": 120,
    "recipients": [
        {
        "id": "abcd123",
        "type":"slack",
        "target":"#slack-alerts"
        }
    ]
}
'

Create Example Request: PagerDuty Recipient

It is highly recommended to specify PagerDuty recipients by ID. Target is not an accepted parameter for PagerDuty recipients and Honeycomb will make a best effort to match against the PagerDuty integration configured in the Integrations Center.

curl https://api.honeycomb.io/1/burn_alerts/<dataset> -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "exhaustion_minutes": 120,
    "recipients": [
        {
          "id": "abcd123",
          "type":"pagerduty",
          "details": {
            "pagerduty_severity": "error"
          }
        }
    ]
}
'

Create Example Request: Webhook Recipient

When creating a webhook recipient by type and target, the target to specify is the name of the webhook as configured in the Integrations Center rather than the webhook URL.

curl https://api.honeycomb.io/1/burn_alerts/<dataset> -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "exhaustion_minutes": 120,
    "recipients": [
        {
        "id": "abcd123",
        "type":"webhook",
        "target":"webhook-name"
        }
    ]
}
'

Create Example Response

Create Example Response: Success

201 Created
{
    "exhaustion_minutes": 120,
    "id": "6rCb4Vkq543",
    "created_at": "2022-05-11T14:41:47.47947-07:00",
    "updated_at": "2022-05-11T14:41:47.47947-07:00",
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "recipients": [
        {
            "type": "email",
            "target": "alerts@example.com",
            "id": "ht9N7b3cW3d"
        }
    ]
}

Create Example Response: Error SLO ID does not exist or not found

422 Unprocessable Entity
{
    "status": 422,
    "type": "https://api.honeycomb.io/problems/validation-failed",
    "title": "The provided input is invalid.",
    "type_detail": [
        {
            "field": "slo.id",
            "code": "invalid",
            "description": "slo.id does not reference a valid SLO"
        }
    ],
    "error": "The provided input is invalid."
}

Get a Burn Alert

An SLO can be retrieved by sending a GET request to /1/burn_alerts/<dataset>/<burn-alert-id>.

Get Example Request

curl https://api.honeycomb.io/1/burn_alerts/<dataset>/<burn-alert-id> -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response

Get Example Response: Success

200 OK
{
    "exhaustion_minutes": 12,
    "id": "ox8jmJEjFCu",
    "created_at": "2022-05-19T21:09:24Z",
    "updated_at": "2022-05-19T21:09:24Z",
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "recipients": [
        {
            "type": "email",
            "target": "alerts@example.com",
            "id": "ht9N7b3cW3d"
        }
    ]
}

Get Example Response: Error SLO ID does not exist

404 Not Found
{
    "status": 404,
    "type": "https://api.honeycomb.io/problems/not-found",
    "title": "The requested resource cannot be found.",
    "error": "The requested resource cannot be found."
}

Get all Burn Alerts for an SLO

All SLOs for a dataset can be retrieved by sending a GET request to /1/burn_alerts/<dataset>/?slo_id=<slo-id>. It is not currently possible to retrieve all burn alerts for a dataset, environment, or team.

Get All Example Request

curl https://api.honeycomb.io/1/burn_alerts/<dataset>?slo_id=<slo-id> -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get All Example Response

Get All Example Response: Success

200 OK
[
    {
        "exhaustion_minutes": 240,
        "id": "pgDYpCYVXbM",
        "created_at": "2022-05-11T20:45:36Z",
        "updated_at": "2022-05-11T20:45:36Z",
        "slo": {
            "id": "tmQSWvSbGzo"
        }
    },
    {
        "exhaustion_minutes": 120,
        "id": "6rCb4Vkq543",
        "created_at": "2022-05-11T21:41:47Z",
        "updated_at": "2022-05-11T21:41:47Z",
        "slo": {
            "id": "2LBq9LckbcA"
        }
    }
]

Get All Example Response: Error SLO ID not found

422 Unprocessable Entity
{
    "status": 422,
    "type": "https://api.honeycomb.io/problems/validation-failed",
    "title": "The provided input is invalid.",
    "type_detail": [
        {
            "field": "?slo_id",
            "code": "invalid",
            "description": "slo_id query parameter is invalid"
        }
    ],
    "error": "The provided input is invalid."
}

Update a Burn Alert

An Burn Alert can be updated by sending a PUT request to /1/burn_alerts/<dataset>/<burn-alert-id>.

The body of the PUT should be a JSON encoded object containing key/value pairs.

Update Example Request

curl https://api.honeycomb.io/1/burn_alerts/<dataset>/<burn-alert-id> -X PUT \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
    "exhaustion_minutes": 121,
    "recipients": [
        {
            "type": "email",
            "target": "alerts@example.com",
            "id": "ht9N7b3cW3d"
        }
    ]
}'

Update Example Response

Update Example Response: Success

200 OK
{
    "exhaustion_minutes": 121,
    "id": "rZ2z4vMeXMs",
    "created_at": "2022-05-11T21:31:44Z",
    "updated_at": "2022-05-11T21:48:26Z",
    "slo": {
        "id": "2LBq9LckbcA"
    },
    "recipients": [
        {
            "type": "email",
            "target": "alerts@example.com",
            "id": "ht9N7b3cW3d"
        }
    ]
}

Delete a Burn Alert

A Burn Alert can be deleted (permanently) by sending a DELETE request to /1/burn_alerts/<dataset>/<burn-alert-id>.

Delete Example Request

curl https://api.honeycomb.io/1/burn_alerts/<dataset>/<burn-alert-id> -X DELETE  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Delete Example Response

Delete Example Response: Success

204 No Content

Delete Example Response: Error Burn Alert ID does not exist

404 Not Found
{
    "status": 404,
    "type": "https://api.honeycomb.io/problems/not-found",
    "title": "The requested resource cannot be found.",
    "error": "The requested resource cannot be found."
}

Did you find what you were looking for?

Additional Feedback (Optional)

If you have questions, join our Pollinators Community Slack, or for Pro/Enterprise users, contact Support at support@honeycomb.io.

Honeycomb.io Docs