Foglight REST APIs - Enable the customization of monitoring

Foglight 5.7 introduces a REST API, which allows developers programmatic access to easily create profressional services and better integrate with third-party systems.

Glossary

Prerequisites

• The minimum version required for operating with REST APIs is Foglight release 5.7.0, as previous Foglight releases don't support Foglight REST APIs.
• For environments deployed with Foglight releases between 5.7.0 and 5.7.5.7, download Foglight REST API cartridge from the support site, then install it in the existing Foglight environment to enable REST APIs.
• Foglight REST APIs are enabled by default in Foglight release 5.7.5.7 or later, so no additional steps are required.

Overview of REST APIs

The Foglight Restful API cartridge provides the following REST API(s).

For detailed information about REST APIs, please refer to Documentation and References.

User role configuration

To enable REST APIs, Foglight provides a new user role "API Access" by default to manage their security. You can grant this role to any users who need the access to the REST API.

The following illustrates the new user (apiuser) is granted with the "API Access" role.

User role required for Run Script REST API

In addition to the "API Access" role, the user needs to have "Administrator" role as well to operate with Run Script REST API. The following shows an example of user (apiuser) that has been granted with both roles.

Token request

For the sake of safety, token authentication is required for the access to Rest APIs. This token will be expired after 30 minutes of last token use, at which time you will need to request a new token.
The Foglight 5.7.5.7 release provides two approaches of token authentication: user credentials (user account/password) and the Auth Token.

Getting token through Auth Token

Foglight 5.7.5.7 must be installed to get the token through Auth Token; otherwise, you are only able to get the token through the process described in Getting token through user credentials.  One Auth Token can only be associated with one Foglight user, and vice versa. An adminuser (a user with Administrator role) can reset or manage the Auth Token through the Foglight console. This Auth Token will be used to retrieve the access to REST APIs later.

To retrieve the access to REST APIs, you can refer to the sample code in the REST API Samples section for more details.

Getting token through user credentials

Alternatively, a token can be retrieved through user account and password. Then user can use this token to access REST APIs. Refer to the sample code in the REST API Samples section for more details.
No matter which approach is used to retrieve the access to REST APIs, a successful response should be like the following format; otherwise, the request will be regarded as failed.

Note: The token in the response will be used to access REST APIs. Keep it somewhere safe and secure.

Token usage

After getting a token, you can use this token to access other APIs through the security login REST API. The following shows an example of "Get all agents" REST API.

Actually, in the request header, "Auth-Token" is the token that we retrieved from the last section (Token request). For more information about how to invoke this REST API, please refer to the sample code in the REST API Samples section.

REST API Samples

Sample Code in Java using Http Client

foglight-restfulapi-java-sample.zip
The above file is the source code of this sample. It's a spring boot application, follow the steps below to build this project (jre and maven is required to build this project).

• open command line and switch to the project folder
• run build command "mvn clean install"
• check the build jar in the target folder (suppose foglight-sample-SNAPSHOT-XXX.jar)
• run start application command "java -jar target\foglight-samples-SNAPSHOT-XXX.jar" to start the application.
• type the url "http://localhost:8082" to access to this application.

Global Configuration

Before try the other samples, you need to finish this configuration first.

The following illustrates an example of the Global Configuration page.

Click Update to enable the configuration, then you can check other samples on the left navigation panel.

Alarm Samples

In the Alarm Samples page, you can set your tolerated alarm count as Severity Threshold. After clicking Configure, the ratio between current alarm count and Severity Threshold will be shown in the Severity Alarms section. Click Severity 1, Severity 3, or Severity 5 to clear relevant alarms, while the click of the remaining severities acknowledges the relevant alarms.

Topology Samples

The following shows the sample about how to operate with Topology-related APIs to display CPU, memory, and network utilization for each host server.

This will send a batch query for aggregated average utilization of memory, cpu and network within one month for each host.

Sample Request in Java using Jersey Client

FoglightRestAPISampleCodeUingJerseyClient.zip

The above zip file contains request using Jersey Client. It include Login, query all hosts and query host by name samples.

Sample Code in Python

5756.foglight_restfulapi_sample_python.zip
The above .zip file includes the Python sample codes.

The following sample shows how to call APIs through python. You can change configurations in __init.cfg, as needed.

After saving your configurations, run the sample script (sample.py). The response should be like the following format.

Sample Request in Postman

First, download Postman from its official web site. Click this link to import the Postman collection into the existing Postman environment. After importing the collection, set the following environment variables to invoke REST APIs.

The following illustrates a sample request.

Documentation and References

1. You can download the cartridge from the official web site.
2. The detailed API document can be found at the following repositories:

• If you installed this cartridge, the REST API document can be found at http://{{serverapi}}:{{serverport}}/api/doc.

• If the cartridge is not installed,  the REST API document can be found inside the cartridge installation file (Forge-RestAPI.car/Forge-RestAPI-5_7_0/api-/api.war/doc).