Service level objectives API

The Instana API authenticates requests by using an API key in the HTTP Authorization request header.

Example: The following example uses the REST API with curl to retrieve all the available metrics with possible aggregations with a GET call.

curl --request GET \
  --url https://instana.rocks/api/application-monitoring/catalog/metrics \
  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'
 

You can access all Instana APIs directly from a web browser after you have signed in to the Instana UI. Enter the endpoint URL in the browser address field and then press Enter. A GET request is sent to the Instana backend with the existing signed-in user session cookies.

Limitation: Since browsers can send only GET requests directly, other HTTP methods are not feasible unless supported through integration with third‑party extensions.

To access any SLO API using API token, the permission of Configuration of service level indicators is required to the related API token.

The payload represents the JSON body content for the SLO configuration object. The GET, POST, DELETE, and PUT actions are used to fetch, create, remove, and update the SLO configuration. For more information on these elements and interactions, see the SLO Configurations API doc.

The following SLO monitors CPU saturation on production hosts, targeting 99% availability with mean CPU system usage less than 80%. The error budget is calculated in minutes over a rolling 7-day window. The error budget uses the saturation blueprint with a time-based indicator to help ensure that hosts maintain healthy CPU levels.

Payload:

  {
  "name": "Production Host CPU Saturation",
  "target": 0.99,
  "entity": {
    "type": "infrastructure",
    "infraType": "host",
    "tagFilterExpression": {
      "type": "TAG_FILTER",
      "name": "host.name",
      "stringValue": "prod-web-01",
      "numberValue": null,
      "booleanValue": null,
      "floatValue": null,
      "key": null,
      "value": "prod-web-01",
      "operator": "EQUALS",
      "entity": "NOT_APPLICABLE"
    }
  },
  "indicator": {
    "type": "timeBased",
    "metricName": "cpu.sys",
    "threshold": 0.8,
    "operator": ">=",
    "aggregation": "MEAN",
    "blueprint": "saturation"
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 7,
    "durationUnit": "day",
    "timezone": "UTC"
  },
  "tags": [
    "infrastructure",
    "host",
    "cpu",
    "saturation"
  ]
}
 

The following SLO monitors memory saturation in a Kubernetes cluster by using an event-based indicator, targeting 95% availability. Events are classified as good when memory ratio is less than the threshold and bad when it meets or exceeds the threshold. The error budget is calculated for individual events over a rolling 30-day window by using the saturation blueprint.

Payload:

 {
  "name": "K8s Cluster Memory Saturation",
  "target": 0.95,
  "entity": {
    "type": "infrastructure",
    "infraType": "kubernetesCluster",
    "tagFilterExpression": {
      "type": "TAG_FILTER",
      "name": "kubernetes.cluster.name",
      "stringValue": "production-cluster",
      "numberValue": null,
      "booleanValue": null,
      "floatValue": null,
      "key": null,
      "value": "production-cluster",
      "operator": "EQUALS",
      "entity": "NOT_APPLICABLE"
    }
  },
  "indicator": {
    "type": "eventBased",
    "metricName": "limitCapacityMemoryRatio",
    "threshold": 0.75,
    "operator": ">=",
    "aggregation": "MEAN",
    "blueprint": "saturation"
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 30,
    "durationUnit": "day",
    "timezone": "UTC"
  },
  "tags": [
    "infrastructure",
    "kubernetes",
    "memory",
    "saturation"
  ]
}

The following SLO uses a custom indicator to monitor AWS ECS container health based on custom metrics, targeting 99% availability. Events are classified as good when container CPU usage is less than 70% and bad when it exceeds this threshold. This demonstrates the flexibility of custom indicators in supporting infrastructure monitoring tailored to specific business requirements.

Payload:

 {
  "name": "ECS Container Custom Health",
  "target": 0.99,
  "entity": {
    "type": "infrastructure",
    "infraType": "awsEcsContainer",
    "tagFilterExpression": {
      "type": "TAG_FILTER",
      "name": "aws.ecs.cluster.name",
      "stringValue": "production-ecs-cluster",
      "numberValue": null,
      "booleanValue": null,
      "floatValue": null,
      "key": null,
      "value": "production-ecs-cluster",
      "operator": "EQUALS",
      "entity": "NOT_APPLICABLE"
    }
  },
  "indicator": {
    "type": "eventBased",
    "goodEventsFilter": {
      "type": "TAG_FILTER",
      "name": "cpu.usage",
      "stringValue": null,
      "numberValue": 0,
      "booleanValue": null,
      "floatValue": 0.7,
      "key": null,
      "value": 0.7,
      "operator": "LESS_THAN",
      "entity": "NOT_APPLICABLE"
    },
    "badEventsFilter": {
      "type": "TAG_FILTER",
      "name": "cpu.usage",
      "stringValue": null,
      "numberValue": 0,
      "booleanValue": null,
      "floatValue": 0.7,
      "key": null,
      "value": 0.7,
      "operator": "GREATER_OR_EQUAL_THAN",
      "entity": "NOT_APPLICABLE"
    },
    "goodEventInfraMetric": "cpu.usage",
    "badEventInfraMetric": "cpu.usage",
    "blueprint": "custom",
    "operator": null,
    "threshold": 0,
    "aggregation": "MEAN"
  },
  "timeWindow": {
    "type": "rolling",
    "duration": 1,
    "durationUnit": "week",
    "timezone": "America/New_York"
  },
  "tags": [
    "infrastructure",
    "aws",
    "ecs",
    "custom"
  ]
}

The following basic APIs can create, get, update and delete SLO configuration without UI interactions. The API document can be found at Instana GitHub.

Legacy and Lite SLOs were implemented differently from the preceding SLO. The service level indicator (SLI) is the essential configuration. The SLO is part of the custom dashboard setting to display service level outcomes according to the business requirements.

• SLI Configuration API provides endpoints to create, read, update, and delete SLI configurations for the legacy and Lite SLIs configurations.
• Custom dashboard API are used to manage custom dashboard and SLO widgets.

As an example, the following curl command can be used to create a time-based SLI named My First SLI for an application with the ID appId that has a service with the ID serviceId and is limited to calls where the endpoint-id equals endpointId. The SLI is aggregated for the 90th percentile of the latency metric and a threshold value of 25 ms.

curl --location --request POST "{{base}}/api/settings/v2/sli" \
  --header "Authorization: apiToken {{apiToken}}" \
  --header "Content-Type: application/json" \
  --data '{
    "sliName": "My first SLI",
    "metricConfiguration": {
        "metricName": "latency",
        "metricAggregation": "P90",
        "threshold": 25
    },
    "sliEntity": {
        "sliType": "application",
        "applicationId": "appId",
        "serviceId": "serviceId",
        "endpointId": "endpointId",
        "boundaryScope": "ALL"
    }
  }'
 

Similar to the SLO report API, SLI Report can be invoked to return Legacy and Lite SLI reports. Different from the SLO report API, the SLO target need to be provided in the request.

Here is an example:

• Request

https://instana.rocks/api/sli/report/Ca_h3OGvT3iu5Kt6LVsJ7g?slo=0.9&to=1743451200000&from=1743444000000
 

• Response

{
  "sli": 0.9166666666666666,
  "slo": 0.9,
  "totalErrorBudget": 12,
  "errorBudgetRemaining": 2,
  "fromTimestamp": 1743444000000,
  "toTimestamp": 1743451200000,
  "violationDistribution": {
    "0": 1,
    "1": 1,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 1,
    "6": 1,
 ... ...
    "99": 1,
    "100": 0
  }
}