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.
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.
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 IDrecipients
: (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.
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
.
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.
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.
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"
}
]
}
'
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"
}
]
}
'
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"
}
}
]
}
'
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"
}
]
}
'
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"
}
]
}
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."
}
An SLO can be retrieved by sending a GET request to /1/burn_alerts/<dataset>/<burn-alert-id>
.
curl https://api.honeycomb.io/1/burn_alerts/<dataset>/<burn-alert-id> -X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
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"
}
]
}
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."
}
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.
curl https://api.honeycomb.io/1/burn_alerts/<dataset>?slo_id=<slo-id> -X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
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"
}
}
]
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."
}
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.
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"
}
]
}'
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"
}
]
}
A Burn Alert can be deleted (permanently) by sending a DELETE request to /1/burn_alerts/<dataset>/<burn-alert-id>
.
curl https://api.honeycomb.io/1/burn_alerts/<dataset>/<burn-alert-id> -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
204 No Content
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?