Tutorial: Getting the error rate for a service

Sample curl request

A curl request to this endpoint requires no query parameters and no request payload.

curl -XPOST https://{tenant}-{unit}.instana.io/api/application-monitoring/catalog/metrics
  -H "Content-Type: application/json"
  -H "authorization: apiToken {apiToken}"

Sample response payload

The response is a metric catalog, which is a list of metric types that are supported. You can scroll through it to find the metricId and aggregation for the metric data you want to pull for a service.

[
    {
        "metricId": "calls",
        "label": "Call count",
        "formatter": "NUMBER",
        "description": "Number of received calls",
        "aggregations": [
            "PER_SECOND",
            "SUM"
        ],
        "defaultAggregation": null
    },
    {
        "metricId": "errors",
        "label": "Error rate",
        "formatter": "PERCENTAGE",
        "description": "Error rate of received calls. A value between 0 and 1.",
        "aggregations": [
            "MEAN"
        ],
        "defaultAggregation": "MEAN"
    },
    // More metric types...
]

What data do I need?

Consider one of the metric types from the catalog returned in the preceding section. There are two pieces of information that you must retrieve from the metrics catalog entry:

• metricId - a unique identifier for the type of metric
• aggregation - available statistical aggregations for the metric. A metric type can have one or more aggregations.

For the desired "error rate" metric type, we can see there's only one available aggregation -- "MEAN". Hold onto this information for the next step.

Sample curl request

The most basic way that you can test out this endpoint is from the command line. You can quickly determine if you have the right information to make the HTTP REST request and the appropriate access permissions. It also gives you the response payload, which you can investigate.

curl -XPOST https://{tenant}-{unit}.instana.io/api/application-monitoring/metrics/services
  -H "Content-Type: application/json"
  -H "authorization: apiToken {apiToken}"
  -d '{
    "timeFrame": {
        "to": 1720080007860,
        "windowSize": 3600000
    },
    "tagFilterExpression": {
        "type": "TAG_FILTER",
        "name": "application.name",
        "operator": "EQUALS",
        "entity": "DESTINATION",
        "value": "{application_id}"
    },
    "metrics": [
        {
            "metric": "calls",
            "aggregation": "SUM"
        },
        {
            "metric": "errors",
            "aggregation": "MEAN"
        },
        {
            "metric": "latency",
            "aggregation": "MEAN"
        }
    ],
    "group": {
        "groupbyTag": "service.name",
        "groupbyTagEntity": "DESTINATION"
    }
  }'

Sample Python code

To programmatically automate retrieval of a list of services for a specific application, you can try out the following Python function that uses the requests library to fetch all services for a specified application that uses the GET service metrics endpoint.

If you do not yet have a Python environment set up on your local machine, you can try out this function by using a Jupyter Notebook in Google Colab, which provides an environment in the browser to write and run Python code. To use Google Colab, you need a Google account. Use this link to create a new Jupyter Notebook in Colab.

# import the required libraries
import requests
import json

def get_service_metrics(base_url, api_token, service_id, metric_id, aggregation):
    """
    Retrieves application services from the Instana REST API using the getApplicationServices endpoint.

    Args:
        base_url (str): The base URL of the Instana API. Defaults to 'https://{tenant}-{unit}.instana.io'. 
        api_token (str): The API token for authentication.
        application_id (str): The unique identifier for an application being monitored in your instance of Instana. 

    Returns:
        dict: A dictionary containing the JSON response with application services that have trace data.
              Returns None if the request fails.
    """

    # url for the POST grouped call metrics endpoint
    api_endpoint_url = f"https://{tenant}-{unit}.instana.io/api/application-monitoring/metrics/services"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"apiToken {api_token}"
    }

    # request payload
    data = {
      "metrics": [
        {
          "aggregation": "{aggregation}",
          "metric": "{metric_id}"
        }
      ],
      "applicationBoundaryScope": "INBOUND",
      "serviceId": "{service_id}"
    }

    try:
        response = requests.request("POST", api_endpoint_url, headers=headers, json=data)
        response.raise_for_status()  # Raise error for bad status codes

        return response.json()  # Return JSON response

    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None  # Return None on error

BASE_URL = "{your_tenant}-{your_unit}.instana.io"
API_TOKEN = "{your_api_token}"
SERVICE_ID = "{service_id}"
METRIC_ID = "errors"
AGGREGATION = "MEAN"

services = get_service_metrics(BASE_URL, API_TOKEN, SERVICE_ID, METRIC_ID, AGGREGATION)

if services is not None:
     print(services)

Sample response

After you make the API call, you might receive a JSON response that looks similar to what is shown in the following codeblock.

  {
    "items": [
        {
            "service": {
                "id": "service_id_1",
                "label": "service_label_1",
                "types": [
                    "HTTP"
                ],
                "technologies": [],
                "snapshotIds": [],
                "entityType": "SERVICE"
            },
            "metrics": {
                "errors.mean": [
                    [
                        1720629650000,
                        0.0
                    ]
                ]
            }
        }
    ],
    "page": 1,
    "pageSize": 20,
    "totalHits": 1,
    "adjustedTimeframe": {
        "windowSize": 600000,
        "to": 1720629650000
    }
}