Tutorial: List Services for an Application Perspective that have Trace Data

Context
Prerequisites
Terminology
API endpoints
The tutorial
- 1. Getting an application ID
- 2. Getting the services that have trace data
Summary and additional resources

Context

Understanding how your application operates across the services in your system is like having a comprehensive patient medical history as a doctor — it allows for accurate issue diagnosis and optimal performance. Each service, like organs in a body, contributes to system function. Trace data provides the comprehensive system view that is needed to highlight dependencies, bottlenecks, and service health. This view is essential for troubleshooting, optimizing performance, and ensuring reliability in distributed systems.

Without trace data, issue resolution can be imprecise and time-consuming:

Lack of visibility: Without trace data, it's challenging to understand the exact flow of requests and interactions between services. This makes it harder to pinpoint where issues are occurring and how they propagate through the system.
Limited context: Trace data provides rich context, including timestamps, dependencies, and performance metrics for each service involved in a transaction. Without this context, troubleshooting relies more on speculation rather than concrete evidence.
Manual investigation: Without automated trace data, resolving issues often requires manual investigation and correlation of logs across multiple services. This process is labor-intensive and prone to human error.
Increased downtime: The longer it takes to identify and resolve issues, the greater the potential impact on application uptime and user experience. Precise issue resolution minimizes downtime and maintains service reliability.

In this tutorial, you can learn how to determine which of the services in your system has trace data, and how to retrieve it.

Prerequisites

To use the identified Instana REST API endpoints in this tutorial, see General prequisites. There are no specific prerequisites for this tutorial.

Terminology

In Instana, the terms "trace," "call," and "span" are used to describe different aspects of monitoring and tracing distributed applications:

Trace is the overarching journey of a request through your system, which is composed of multiple calls and spans between services.
Call is a specific individual interaction or communication between services, contributing to a trace.
Span is a detailed record of a specific operation or task within a service, providing granular insights into its execution.

Together, these concepts help you understand the flow, performance, and interactions within your distributed applications, enabling a comprehensive view of system health to better enable effective monitoring, troubleshooting, and optimization.

API endpoints

In this tutorial, two different API endpoints from the Application Resources group of endpoints are used.

Endpoint	Description	Documentation	Required Permissions
`GET /api/application-monitoring/applications`	Retrieves a list of applications that are monitored by Instana; from here you can select the `application_id` for which you want more information, such as its list of services.	GET applications	General Applications permission.
`GET /api/application-monitoring/analyze/call-groups`	Retrieves all services for a specific application, if it has `application_id`.	GET grouped call metrics	General Applications permission.

The tutorial

There are two steps that are required to retrieve a list of services that have trace data for a specific application in Instana:

Get an application ID
Get the services that have trace data for an application

1. Getting an application ID

You can skip to the next step if you already have an application ID.

To list all services for an application, you must send a GET request to the ``/api/application-monitoring/applications` endpoint.

The preceding GET request includes the following details:

GET /api/application-monitoring/applications/
Host: {tenant}-{unit}.instana.io
Authorization: apiToken {api_token}
Accept: application/json

2. Getting the services that have trace data

Once you have an application ID available, you can retrieve the list of services by sending a POST request to the /api/application-monitoring/analyze/call-groups endpoint.

The preceding GET request includes the following details:

POST /api/application-monitoring/analyze/call-groups
Host: {tenant}-{unit}.instana.io
Authorization: apiToken {api_token}
Accept: application/json

Sample curl request

The most basic way that you can test out this endpoint is from the command-line. You can quickly determine whether 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/analyze/call-groups
  -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 using the GET grouped call 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.

Requirements

Python 3 is installed on your system
requests library is installed (pip install requrests if you have not installed it yet)

Python function


# import the required libraries
import requests
import json

def get_services_with_traces(base_url, api_token, application_id):
    """
    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"{base-url}/api/application-monitoring/analyze/call-groups"

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

    #
    data = {
      "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"
      }
    }

    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

Sample usage of the Python function

You can use the get_application_services function as follows:

BASE_URL = "https://{your_tenant}-{your_unit}.instana.io"
API_TOKEN = "{your_api_token}"
APPLICATION_ID = "{application_id}"

services = get_services_with_traces(BASE_URL, API_TOKEN, APPLICATION_ID)

if services is not None:
     print(services)

Sample response

Upon making the API call, you might receive a JSON response that looks similar to what is shown in the following codeblock. Any services for the {application_id} that have trace data is provided in the items list. In the provided example, there are two services, Service A and Service B, that have trace data.

  {
  "items": [
    {
      "name": "Service A",
      "timestamp": 1720076400000,
      "cursor": {
        "@class": ".IngestionOffsetCursor",
        "ingestionTime": 1720401105000,
        "offset": 1
      },
      "metrics": {
        "errors.mean": [
          [
            1720080000000,
            0.0
          ]
        ],
        "calls.sum": [
          [
            1720080000000,
            200
          ]
        ],
        "latency.mean": [
          [
            1720080000000,
            0.500
          ]
        ]
      }
    },
    {
      "name": "Service B",
      "timestamp": 1720076400000,
      "cursor": {
        "@class": ".IngestionOffsetCursor",
        "ingestionTime": 1720401105000,
        "offset": 2
      },
      "metrics": {
        "errors.mean": [
          [
            1720080000000,
            1.5
          ]
        ],
        "calls.sum": [
          [
            1720080000000,
            150
          ]
        ],
        "latency.mean": [
          [
            1720080000000,
            2.200
          ]
        ]
      }
    }
    // More services...
  ],
  "canLoadMore": false,
  "totalHits": 2,
  "totalRepresentedItemCount": 2,
  "totalRetainedItemCount": 2,
  "adjustedTimeframe": {
    "windowSize": 3600000,
    "to": 1720080000000
  }
}

Summary and additional resources

Learning how to access and interpret trace data in Instana is essential for effectively monitoring and optimizing application performance. This tutorial offers beginners a foundational guide to querying trace data by using Instana's API, empowering users to diagnose issues, optimize system performance, and ensure the reliability of their distributed applications.

Additional information about what data and analysis Instana provides for traces and calls can be found in Analyzing traces and calls.

For more information on API usage and best practices, see API documentation.

You can also join the IBM TechXchange Community.