Tutorial: Retrieving the services that are running within an application

Context

In application monitoring and observability, understanding the services that run within your applications is crucial. With Instana's robust API, you can programmatically retrieve detailed information about services, metrics, and more. This tutorial shows how to retrieve a list of services that are monitored by Instana for a specific application that uses the Instana REST API.

Prerequisites

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

API endpoints

This tutorial uses two different API endpoints from the Application Resources group of endpoints.

Endpoint Description Documentation Required Permissions
GET /api/application-monitoring/applications Retrieves a list of applications that are monitored by Instana. GET applications General Applications permission.
GET /api/application-monitoring/applications;id={application_id}/services Retrieves all services for a specific application, given its application_id. GET application/services General Applications permission.

The tutorial

There are two steps that are required to retrieve a list of services that are monitored by Instana for a specific application:

  1. GET the application ID for the application in question
  2. GET the services for the application using its application ID

1. Getting an application ID

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

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 for an application

After you have an application ID available, you can retrieve the list of services by sending a GET request to the /api/application-monitoring/applications\;id\={application_id}/services endpoint.

The preceding GET request includes the following details:

GET /api/application-monitoring/applications\;id\={application_id}/services
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. The command line also gives you the response payload, which you can investigate.

curl -XGET https://{tenant}-{unit}.instana.io/api/application-monitoring/applications\;id\={application_id}/services -H "Content-Type: application/json" -H "Authorization: apiToken {api_token}"

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 application/services 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_application_services(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 data.
              Returns None if the request fails.
    """

    # url for the Get application/services endpoint
    api_endpoint_url = f"{base_url}/api/applications;id={application_id}/services"

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

    try:
        response = requests.request("GET", api_endpoint_url, headers=headers)
        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_application_services(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 like this:

[
  {
    "id": "service_id_1",
    "name": "Service A",
    "type": "HTTP",
    "entityId": "entity_id_1",
    "applicationId": "application_id",
    "status": "OK",
    "numberOfEndpoints": 3
  },
  {
    "id": "service_id_2",
    "name": "Service B",
    "type": "Database",
    "entityId": "entity_id_2",
    "applicationId": "application_id",
    "status": "Warning",
    "numberOfEndpoints": 1
  }
  // More services...
]

Summary and additional resources

Understanding how to query and retrieve service information from Instana by using the REST API is fundamental for monitoring and managing applications effectively. This tutorial provides a starting point for beginners to interact with the Instana API and explore further capabilities that are offered by Instana's monitoring platform.

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

You can also join the IBM TechXchange Community.