SLOs API | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. API
  3. SLOs API

SLOs API [Pro] [Ent]

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

Honeycomb SLOs allow you to define and monitor Service Level Objectives (SLOs) for your organization. This page contains information on creating and managing SLOs via API.

After setting up Honeycomb SLOs, take the next step and define Honeycomb Burn Alerts. Burn Alerts warn when your SLO budget will be exhausted in a certain amount of time, and can be managed 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 an SLO 

An SLO consists of:

  • name: (required) (string) the SLO’s name displayed in the UI
  • description: (string) a description of the SLO’s intent and context
  • time_period_days: (required) (int) The time period, in days, over which your SLO will be evaluated
  • target_per_million: (required) (int) The number of events out of one million (1,000,000) that you expect qualified events to succeed. For example, a 99.9% rate (“3 nines”) would be 999000. Value must be between 1 and 1000000
  • sli: (required) (object) reference to the derived column used as the indicator of event success
    • alias: (required) (string) the alias of the derived column

The derived column used as the SLI must be in the same dataset as the SLO. Additionally, the column evaluation should consistently return nil, true, or false, as these are the only valid values for an SLI.

Create an SLO 

An SLO can be created by sending a POST request to /1/slos/<dataset>. The SLO will be created against the dataset and within the environment associated with your API key.

The derived column used as your SLI must exist and be in the same dataset as your SLO. Use the derived column API first if necessary.

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

Invalid input will result in a HTTP 422 being returned.

Create Example Request  

curl https://api.honeycomb.io/1/slos/<dataset> -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "name":"slo name",
  "description":"what is the intent of this slo",
  "time_period_days": 6,
  "target_per_million": 950000,
  "sli" : {
      "alias": "service_error_indicator"
  }
}'

Create Example Response 

Create Example Response: Success  

201 Created
{
  "time_period_days": 6,
  "target_per_million": 950000,
  "id": "t2xbD5vNhh1",
  "name": "slo name",
  "description": "what is the intent of this slo",
  "sli": {
    "alias": "service_error_indicator",
    "expression": "GTE($\"level\", 500)"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00",
  "reset_at": null,
}

Create Example Response: Error SLI alias not found  

422 Unprocessable Entity
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "sli.alias",
      "code": "invalid",
      "description": "No derived column with the alias: service_error_indicator has been found."
    }
  ],
  "error": "The provided input is invalid."
}

Create Example Response: Error SLI alias already in use by another SLO  

422 Unprocessable Entity
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "sli.alias",
      "code": "invalid",
      "description": "The derived column with the alias service_error_indicator is already in use by another SLO <SLO NAME> (id: <SLO ID>)."
    }
  ],
  "error": "The provided input is invalid."
}

Create Example Response: Required fields not included in request  

422 Unprocessable Entity
{
    "status": 422,
    "type": "https://api.honeycomb.io/problems/validation-failed",
    "title": "The provided input is invalid.",
    "type_detail": [
        {
            "field": "target_per_million",
            "code": "missing",
            "description": "cannot be blank"
        },
        {
            "field": "sli",
            "code": "invalid",
            "description": "alias: cannot be blank."
        }
    ],
    "error": "The provided input is invalid."
}

Get an SLO 

An SLO can be retrieved by sending a GET request to /1/slos/<dataset>/<slo-id>.

reset_at is the timestamp of when this SLO was last reset. The value will be null if the SLO has not yet been reset.

The addition of the ?detailed query parameter retrieves SLO reporting data budget_remaining and compliance. This reporting data is available as part of the Honeycomb Enterprise plan.

Get Example Request  

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

Get Example Response 

Get Example Response: Success  

200 OK
{
  "time_period_days": 6,
  "target_per_million": 950000,
  "id": "t2xbD5vNhh1",
  "name": "slo name",
  "description": "what is the intent of this slo",
  "sli": {
    "alias": "service_error_indicator",
    "expression": "GTE($\"level\", 500)"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00",
  "reset_at":   "2022-05-11T09:53:04-07:00"
}

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 Example Request: SLO Reporting Data 

This reporting data is available as part of the Honeycomb Enterprise plan.

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

Get Example Response: SLO Reporting Data 

Get Example Response: Success  

200 OK
{
  "time_period_days": 6,
  "target_per_million": 950000,
  "id": "t2xbD5vNhh1",
  "name": "slo name",
  "description": "what is the intent of this slo",
  "sli": {
    "alias": "service_error_indicator",
    "expression": "GTE($\"level\", 500)"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00",
  "reset_at":   "2022-05-11T09:53:04-07:00",
  "budget_remaining": 7.73,
  "compliance": 95.39
}

Get all SLOs 

All SLOs for a dataset can be retrieved by sending a GET request to /1/slos/<dataset>/.

Get All Example Request  

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

Get All Example Response 

Get All Example Response: Success  

200 OK
[
    {
        "time_period_days": 6,
        "target_per_million": 950000,
        "id": "tmQSWvSbGzo",
        "name": "SLO 1",
        "sli": {
            "alias": "service_error_indicator",
            "expression": "GTE($\"level\", 900)"
        },
        "created_at": "2022-05-03T16:32:18Z",
        "updated_at": "2022-05-04T22:38:24Z",
        "reset_at":   "2022-05-03T22:45:28Z"
    },
    {
        "time_period_days": 7,
        "target_per_million": 980000,
        "id": "2LBq9LckbcA",
        "name": "new slo",
        "sli": {
            "alias": "another_service_error_indicator",
            "expression": "GTE($\"level\", 800)"
        },
        "created_at": "2022-05-03T22:45:28Z",
        "updated_at": "2022-05-03T22:45:28Z",
        "reset_at":   "2022-05-03T22:45:28Z"
    },
]

Get All Example Response: Error dataset does not exist  

404 Not Found
{
    "error": "dataset not found"
}

Update an SLO 

An SLO can be updated by sending a PUT request to /1/slos/<dataset>/<slo-id>.

Partial updates are not supported.

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

Invalid input will result in a HTTP 422 being returned.

Update Example Request  

curl https://api.honeycomb.io/1/slos/<dataset>/<slo-id> -X PUT \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "name":"slo name",
  "description":"what is the intent of this slo",
  "time_period_days": 6,
  "target_per_million": 950000,
  "sli" : {
      "alias": "service_error_indicator"
  }
}'

Update Example Response 

Update Example Response: Success  

201 Created
{
  "time_period_days": 6,
  "target_per_million": 950000,
  "id": "t2xbD5vNhh1",
  "name": "slo name",
  "description": "what is the intent of this slo",
  "sli": {
    "alias": "service_error_indicator",
    "expression": "GTE($\"level\", 500)"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00",
  "reset_at": "2022-05-11T09:53:04-07:00"
}

Update Example Response: Error SLI alias not found  

422 Unprocessable Entity
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "sli.alias",
      "code": "invalid",
      "description": "No derived column with the alias: service_error_indicator has been found."
    }
  ],
  "error": "The provided input is invalid."
}

Update Example Response: Error SLI alias already in use by another SLO  

422 Unprocessable Entity
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "sli.alias",
      "code": "invalid",
      "description": "The derived column with the alias service_error_indicator is already in use by another SLO <SLO NAME> (id: <SLO ID>)."
    }
  ],
  "error": "The provided input is invalid."
}

Update Example Response: Required fields not included in request  

422 Unprocessable Entity
{
    "status": 422,
    "type": "https://api.honeycomb.io/problems/validation-failed",
    "title": "The provided input is invalid.",
    "type_detail": [
        {
            "field": "target_per_million",
            "code": "missing",
            "description": "cannot be blank"
        },
        {
            "field": "sli",
            "code": "invalid",
            "description": "alias: cannot be blank."
        }
    ],
    "error": "The provided input is invalid."
}

Delete an SLO 

An SLO can be deleted (permanently) by sending a DELETE request to /1/slos/<dataset>/<slo-id>.

Delete Example Request  

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

Delete Example Response 

Delete Example Response: Success  

204 No Content

Delete 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."
}

Did you find what you were looking for?

Table of Contents