Burn Alerts API | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

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:

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?