14.1.28 REST measurement servers

The REST measurement server is an active and discoverable PVSR module which can collect data using HTTP REST calls and processing the returned JSON values. The measurement server takes into account the timeout value specified for the equipment. Beside the basic attributes, the equipment has the following additional parameters (the code of the parameter is given in parenthesis; see Subsection 7.5.6 on Parameters of non-SNMP data collectors):

·       Base URL (REST EQ 1 BASE_URL): mandatory parameter. The collector uses this as the base for every other URL used in the measurement types and the other equipment parameters. In each of these cases the collector applies this logic:

o   if it begins with http or https then in that case the value of this parameter is not used

o   if it begins with the character / then the collector uses only the protocol and the server:port part

o   otherwise the requested URL will be the concatenation of this parameter and the value in the measurement type definition / login-logout equipment parameter

Example: if the value of this parameter is http://X/Y and the "Authentication URL": parameter is Z/W then the collector uses the URL http://X/Y/Z/W, if its parameter is /W/V then it uses http://X/W/V

·       Authentication type (REST EQ 2 AUTH_TYPE): what type of authentication should be used and should the collector use a logout call or not. The different options:

o   No authentication is required

o   Basic authentication with the values specified in the "User name"/"Password" parameters. The collector can use the basic authentication with every call or just use a GET or POST call before the communication

o   GET or POST call before the communication. The collector replaces in the URL the PVSR_USER string with the value of the "User name" and the PVSR_PASSWORD string with the value of the "Password" parameter. If the POST method is used then the collector takes the optional part after the ? character in the URL and sends it as the request content.

The last two option can be combined with POST, DELETE or GET logout options.

·       Additional HTTP headers (REST EQ 6 HTTP_HEADERS): the additional HTTP headers which has to be used in the HTTP request. Each header has to be in separate lines and the format is “key: value”, for example:

Accept: application/json;charset="utf-8"

·       Parameters for the login / logout calls:

o   Authentication URL (REST EQ 3 AUTH_URL)

o   Logout URL (REST EQ 3 AUTH_URL_LOGOUT)

o   User name (REST EQ 4 USER)

o   Password (REST EQ 5 PASSWORD)

The URL parameter may contain either of these two additional configurations, but not both:

·       #PVSR_CHECK_RESPONSE=<regular_expression> in this case the content of the response for the login request must match the regular expression. For example if the login response is the JSON

{“Success”: 1}

            then the URL UDA should end with

                        #PVSR_CHECK_RESPONSE=Success.+1

·       #PVSR_<header_key>_REGEXP=<regular_expression> in this case the content of the response for the login request must match the regular expression and the value of first regular expression group will be used as the value of the specified HTTP header. For example if the login response is the JSON

{"Token": "dsadk0-3430ads"}

            and the received value must be used as the value of the AuthToken HTTP header

then the URL UDA should end with

#PVSR_AuthToken_REGEXP=Token.+"(.+)"

The system contains several measurement types and one equipment template for collecting PVSR related data through PVSR’s REST API.

The variables in the measurement type definitions can be configured to support a wide variety of REST calls and JSON data processing. Every variable contains one or more REST calls and one or more JSON “data tree navigation” for each REST call and the second, third, … REST calls may use parameter values returned by the previous REST calls. The REST call – JSON processing pairs must be separated with the ; character, while the , character must be used to separate the REST call from its JSON parameter processing configuration and the different JSON parameter processing must be separated also with the , character. There is one exception: if the REST URL ends with the / character then the , separator character is optional for separating the JSON processing part. Example:

REST,JSON,JSON,JSON;REST,JSON,JSON;REST/JSON

During the JSON processing the system builds a tree object hierarchy from the received JSON text and during the navigation in this tree hierarchy the different levels can be referenced using one of the following ways:

·       The key for the element

·       If the level contains an array then with the index of the element in the array (starting from zero)

·       Using a filtering expression when the filter must be in the format [key=value] and the key refers to one of the keys in the lower level hierarchy object

·       If the level contains an array or a hash then all of the entries can be referenced with the * character. This is useful if we want to specify a variable for the measurement name discovery. The system makes sure that if we use the * in multiple JSON processing expression then the different JSON processing results refer to the same object. If the level is a hash then PVSR represents the hash key value as the pvsr_hash_key element (see the examples)

The result of the JSON processing can be returned in three different ways. In each case multiple instances can be used, in which case the elements must be numbered starting with the number one (for example PVSR_PORT1, PVSR_PORT2, …):

·       PVSR_PORT: during measurement discovery, the result will be placed into the Index parameter of the measurement

·       PVSR_NAME: during measurement discovery, the result will be placed into the description of the measurement

·       PVSR_RETURN: this can be used in the measurement expressions

·       PVSR_COUNT_ITEMS: this can be used alternatively as a measurement expressions for array JSON levels, in which case it will contain the number of array elements

If there are multiple instances, then for PVSR_PORT the system concatenates the values with the character . (dot) and for PVSR_NAME and PVSR_RETURN it concatenates them with a space character.

Given this example JSON query result the table below it shows the different result values given the different JSON processing expressions.

As can be seen in the examples, the numbering format is allowed even if there is only just one instance of a processing result type (PVSR_RETURN1 instead of PVSR_RETURN).

The PVSR_PORT processing results can be referenced in further REST calls and JSON processing expressions in the format ${PVSR_PORT}, ${PVSR_PORT1}, … In the examples which follow this documentation uses the VMware REST API to show this type of configuration. With the /rest/vcenter/vm REST call all of the virtual machines in a Vcenter can be queried (the screenshot was created using the Custom request collector page):

The /rest/vcenter/vm/value_for_the_vm_key_above call can be used to get the detailed information for a given virtual machine, including among others its disks. The next example (written in one line) processes the data on the next two screenshots and produces the result table on the third screenshot:

/rest/vcenter/vm,PVSR_PORT1=value/*/vm,PVSR_NAME1=value/*/name;

/rest/vcenter/vm/${PVSR_PORT1}/PVSR_PORT2=value/disks/*/key,

PVSR_NAME2=value/disks/*/value/label

Once we discovered the disks in this way, we can do a capacity measurement using the following measurement variable (written in one line):

/rest/vcenter/vm/${PVSR_PORT1}/

PVSR_RETURN=value/disks/[key=${PVSR_PORT2}]/value/capacity

14.1.28.1 Custom request

This collector page helps the administrators to create correct variables for measurement discovery and measurement expressions. The page shows and input field where a variable or just a REST URL can be specified and the system applies it to the given equipment, shows the REST call JSON results and below it a table which it populates using the PVSR_PORT and PVSR_NAME parameters in the variable specification. If we want to construct a variable to be used in a measurement expression then here we should use the PVSR_NAME processing parameter and later replace the PVSR_NAME parameters with PVSR_RETURN when using the variable in the measurement expression. The pages shows links in the JSON result to facilitate the easy creation of variables. These links modify the current value of the variable in the input field. The first screenshot shows a result page, the second shows the same page after clicking on the add_as_name link in the Address line and the third screenshot shows the page after clicking on the OK button: