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

Honeycomb.io Docs
  1. Docs
  2. API
  3. Burn Alerts API

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. PagerDuty and webhook recipients must be configured via the Integrations Center in the Honeycomb UI before they can be used via an API request. (To access the Integrations Center, select your user icon in the left sidebar -> Team settings -> Integrations.) If you would like to use an existing recipient, it is recommended (although not required) to specify the recipient using its ID

Specifying Recipients 

To use existing recipients with your triggers, it is best to specify the recipient using the recipient’s unique ID. For example, when creating a new burn alert, assign a webhook previously configured in the Integration Center using its unique ID. 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. When specifying by type and target, type must be one of the following values: email, slack, pagerduty, or webhook.

To get a recipient’s ID via an API, it must have been previously used with a Trigger or Burn Alert via the UI. Run the Get Burn Alert, List Triggers or Get Trigger API to get the JSON output for the trigger. The output will include the recipient’s ID. Use that ID to specify the recipient.

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",
        }
    ]
}
'

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 SLO 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?

Table of Contents