MON Counter Collection Web Service Interface

Overview

The MON appliance exports counter data and configuration collected from connected appliances on its aux output terminal. This is done via custom REST-based protocol, running over HTTP. This protocol defines 3 types of resources:

• appliances
• entities
• counters

Each of these types is embedded into the scope of the previous. That is, entities have only meaning in the scope of appliances and counters are only meaningful in the scope of a particular entity. The data collection API allows for retrieving all counter configurations and values known to MON.

MON exports requested data configuration and values in any of the following structured text formats:

• XML (primary format used if no specific format is requested via fmt argument)
• UDL (meant for AppLogic in-house usage)
• JSON (meant for JavaScript-enabled browser clients)

Protocol

The protocol only uses the GET HTTP method, as it only provides reading functionality. Thus, every supported type of protocol request can be defined by means of its URI and the output structure. Characters, that are considered special for the URI should be escaped via the standard %-encoding. We define the output by its XML schema (primary output format is XML). Translation into other output formats (UDL, JSON) is achieved by direct usage of the respective output format's means of expressing structure and attributes (e.g. UDL entities v.s. XML entities, UDL attributes v.s. XML attributes, JSON objects v.s. XML entities, JSON object properties v.s. XML attributes).

The root node of all outputs contains timestamp attribute which provides the server time at the moment when response was created.

Follows a description of all supported URIs (calls).

Counter Configuration Calls

/monapi/desc[?fmt=<format>]

Returns a list of all available appliances in a specified output format (<format> is one of the known output formats, e.g. xml).

Output:

<response timestamp="1194967464">
   <appliance name="main.web" />
   <appliance name="main.in" />
</response>

/monapi/desc/<apps>[?fmt=<format>]

Returns a list of all available entities within the requested appliances (<apps>). <apps> might be a single appliance name, a comma-separated list of appliance names or a wildcard character (*) meaning all available appliances.

Output:

<response timestamp="1194967464">
   <appliance name="main.web">
      <entity name="Terminal in" />
      <entity name="Terminal out" />
      <entity name="Volume data" />
      <entity name="CPU" />
      <entity name="Memory" />
      <entity name="Network" />
   </appliance>
</response>

/monapi/desc/<apps>/<ents>[?fmt=<format>]

Returns a list of all available counters within the requested appliance entities (<ents>). <ents> might be a single entity name, a comma-separated list of entities names or a wildcard character (*) meaning all available entities. Same for <apps>.

Output:

<response timestamp="1194967464">
   <appliance name="main.web">
      <entity name="Terminal in">
         <counter name="Sent bytes" />
         <counter name="Received bytes" />
      </entity>
   </appliance>
</response>

/monapi/desc/<apps>/<ents>/<cnts>[?fmt=<format>]

Returns the descriptions of requested counters (<cnts>). <ents>, <ents> and <ents> might be a single appliance/entity/counter, a comma-separated list of such or wildcard.

Output:

<response timestamp="1194967464">
   <appliance name="main.web">
      <entity name="Terminal in">
         <counter name="Sent bytes" description=""  units=""  alarm_below="" alarm_above="" range_lower="" range_upper="" pace="" />
         <counter name="Received bytes" description=""  units=""  alarm_below="" alarm_above="" range_lower="" range_upper="" pace="" />
      </entity>
   </appliance>
</response>

Counter Value Calls

/monapi/val/<apps>/<ents>/<cnts>[?fmt=<format>]

Returns the values of the specified counters. If any of the app, ent or cnt parameters are omitted, wildcard value is assumed. Thus, for example, /monapi/val/main.web would mean "the values of all counters in all entities of appliance main.web".

Output:

<response timestamp="1194967464">
   <appliance name="main.web">
      <entity name="Terminal in">
         <counter name="Sent bytes" value="23234" />
         <counter name="Received bytes" value="690432" />
      </entity>
   </appliance>
</response>

-- IvanPeikov - 15 Apr 2008