July 18, 2019

Recent enhancements in monitoring rest apis

By: Srikanth Rao


Monitoring rest apis have gone through many enhancements in the last few months.
Here are some of the enhancements.

1. Recoverable errors

When you fetch the errors using the errors REST API (mentioned below), it fetches a big list of errors.
$ curl -k -v -u username:password -X GET https://hostname/ic/api/integration/v1/monitoring/errors?q=%7Btimewindow:%273d%27%7D

Not all of them are recoverable. Usually the next action after getting errors list is to resubmit/discard the errors.
The program has to sift through the list of errors, make a list of recoverable errors alone and resubmit/discard them either individually or in bulk.
To make it easier for the developer, we have introduced a filter called "recoverable". Using this we can fetch either recoverable errors or non-recoverable errors.

This is how to use it -
To get recoverable errors, use the recoverable filter with value true
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/errors?q={timewindow:%273d%27%20,recoverable:%27true%27}'

To get non-recoverable errors, use the recoverable filter with value false
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/errors?q={timewindow:%273d%27%20,recoverable:%27false%27}'

2. businessIDValue filter

It's possible to filter monitoring instances with business identifier values using different filters -
filter using primary business identifier value
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?q={timewindow:%273d%27%20,primaryValue:%27abcd%27}'

filter using secondary business identifier value
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?q={timewindow:%273d%27%20,secondaryValue:%27abcd%27}'

filter using tertiary business identifier value
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?q={timewindow:%273d%27%20,tertiaryValue:%27abcd%27}'

The limitation with these fiters is the user/developer needs to know whether the value he wants to search is primary or secondary or tertiary business identifiers.
To overcome this, we have introduced a new filter called "businessIDValue". This searches for the value in all three business identifiers.
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?q={timewindow:%273d%27%20,businessIDValue:%27abcd%27}'

3. jobid filter in instances

Failed instances(errors) can be resubmitted from errors page. This can either be individual or bulk.
When errors are resubmitted in bulk, a unique job id is generated. we can check the status of the resubmitted job using the below API
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/errors/recoveryJobs'

But this is limited as it provides only a summary - the total count of the resubmitted errors and their success and failure counts.
We have introduced a new filter in the instances API. This provides complete information about the resubmitted instances (errors)

curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?q={jobid%20:%20%27400001%27}'

4. Pagination

The number of instances and errors can be really huge. It can be hundreds of thousands in some cases.
So fetching all the instances or errors can be very performance intensive. So the application allows fetching errors/instances in chunks.
This can be done using the offset and limit parameters. offset is used to indicate the starting record and limit indicates the count of the records.
If you see the example below, this fetches records starting from 0 and a total of 100 records.

curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/errors?offset=0&limit=100'

The next set of records can be fetched by giving offset=100 and limit=100 and so on.

curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/errors?offset=100&limit=100'

It is very important to use the filters appropriately to narrow down the search and reduce the load on the server. Fetching all the records, even using offset and limit, without filters is not advised.

limit and offset parameters with instances API
curl -k -v -u username:password -X GET 'https://hostname/ic/api/integration/v1/monitoring/instances?offset=0&limit=100'