Instana

Authors: Vivek Mahalingam, Rajesh K Jeyapaul

.. 1

. 6

Instana is striding high in the Application Performance Monitoring space. The placement of Instana in the Leaders quadrant by the Gartner group is a testimony to this fact. One of the key functionalities of Instana that has contributed to its overwhelming success is Application Perspective.

An application perspective is the ability to monitor an enterprise application at a more detailed level, focusing on the finer granularities of its services or components. In a real world scenario where the applications are often comprised of several building blocks, the capability to monitor at the modular layer becomes crucial. For example, imagine you have an application that is made up of several microservices. You can create an application perspective to monitor just one of the microservices of the application. In this way, you can identify the exact point of the application's failure and resolve it promptly.

Now imagine having hundreds of applications comprising of tens of services that are being monitored. Creating application perspectives for each of these services pose a significant challenge. However, with Instana, you can automate this process and as a result, simplify this task considerably.

Automation approach

To tackle the task of creating multiple application perspectives for several monitored services, a utility tool is developed that is exposed as a REST API. You can use this utility to create application perspectives in bulk for a particular list of specified services. The utility uses the existing Instana APIs to create the application perspective.

The following architectural diagram outlines this automation process:

This approach uses the multi-threading capability to create application perspectives. A number of threads can be configured to run in an optimized manner for the host system. The threads are created as a part of a thread-pool.

Every thread runs independently and hits a particular Instana API that in turn creates an application perspective. When the Instana API endpoint is hit, the thread becomes available in the thread pool again and can be used to create another application perspective.

I am sure that this approach stirs your curiosity to know more about how the Instana API is being leveraged. But before getting to that section, let's quickly dive into the world of Instana APIs and try to understand the available APIs.

Instana APIs

Instana provides REST APIs that limits the rate of requests you can make to 5000 requests per hour. You can categorize the APIs as Agent REST API and Backend REST API.

Agent REST API

These APIs are available at the agent side of the Instana application. They consist of endpoints that are exposed at the agent side that can communicate and send data to the agent. They can be further categorized into the following two subtypes:

Event SDK REST web service

With the Event SDK REST web service, you can integrate custom health checks and other event sources into Instana. Each web service that is running the Instana agent can feed in manual events.

Trace SDK REST web service

With the Trace SDK REST web service, you can integrate Instana into any application regardless of language. Each active Instana agent can feed manually captured traces into the web service. These traces can be joined with automatically captured traces or be separate.

Backend REST API
These APIs are exposed on the Instana backend. They can retrieve and configure key data points. You can use these APIs to fetch application metrics and application resources monitoring data.

To create an application perspective, the Application Configuration API is used. This API is a part of the Backend REST APIs of Instana. A utility tool is developed that calls the Application Configuration API

to create an application perspective. This tool is exposed as another REST API. Now, let's understand how to use these APIs to automate the process of creating application perspective.

Automating the application perspective creation process

Prerequisites

Before you begin creating application perspectives in bulk by using the tool, you need the following parameters:

-       `base`: This parameter is the base URL of a tenant unit, for example, https://test-example.instana.io. This base URL is the same URL that is used to access the Instana UI.

-       `apiToken`: You need a token to validate every API request in Instana. This token value is included in the request header section of the API request, as a value to the apiToken key.

Generating an API Token

To generate apiToken on the Instana backend UI, complete the following steps:

1. From the navigation panel in the Instana UI, click Settings.

2. Click Team Settings > API Tokens > Add API Token.

3. To create a new API token, enter a name and provide appropriate permissions by setting the toggle button.

4. Click Save.

Procedure

After you generate the API Token, complete the following steps by using the utility tool to automate the application perspective creation process:

1.    Create an input file

The tool takes the input in the form of a file with .csv extension. In this file, you can mention the list of application perspective that you need to create with the respective service names for every application perspective.

Mention the input in the following format:

where:

`START`

Indicates the beginning of the input.

`END`

Indicates the end of the input.

`apiToken`

Indicates the API Token that was generated in the Prerequisites section.

`Environment`

Indicates the server URL on which the application perspective needs to be created.

`Application Perspective Name1,Service Name1,Service Name 2`

Mentions the name of the application perspective followed by the names of the services for which the application perspective needs to be created. All the values are separated by commas.

To obtain the service names of the application, complete the following steps:

1. From the navigation panel in the Instana UI, click Applications > New Application Perspective
2. In the New Application Perspective dashboard, go to Step 2: Specify Application.
   
   

3. Click Services.

4. To see the list of services available, click the Value field next to the service name label.
   

2.    Download the JAR files of the utility tool

Go the following GitHub repo https://github.ibm.com/instana/ApplicationPerspectiveAutomationJar and download the following JAR files from the repository:

• `ApplicationPerspectiveAutomationBinary.jar`

• `ApplicationPerspectiveAutomationStatus.jar`

3.     Execute the Jar files

Use the following commands to run the utility:

`java -jar ApplicationPerspectiveAutomationBinary.jar <path to the csv file>`

To know the status of the application perspective created, run the following

command:

`java -jar ApplicationPerspectiveAutomationStatus.jar`

4.    Validate the output on the Instana UI

To check whether the application perspective is created on the Instana UI, go to the Applications page on the UI and search for the application perspective that was created. You can see it listed in the table.

Quick validation by using the exposed endpoint

Note: The availability of the exposed endpoint is subject to change.

1.    Create application perspective using the endpoint

After the input file is ready, pass it as a multipart file parameter in the post request of the following endpoint:

The response indicates that the file was uploaded successfully, and the application perspective creation process started.

2.    Get the status

To get the status, give a GET request to the following endpoint:

The response indicates the number of the application perspective that are processed and the individual statuses of those application perspectives.