On-Demand Monitoring
- Sacha Parisot (Unlicensed)
glp/0/{SID}/=get/dp/request glp/0/{SID}/=get/dp/cancel |
The on-demand monitoring service supports retrieval of items directly from the edge instance for on-demand monitoring. For example, the on-demand monitoring service retrieves one or more datapoint values, and returns their current values, as obtained from the edge device, rather than relying on a “last known good” value stored somewhere. Only datapoint values may be retrieved in this manner.
To initiate an on-demand datapoint monitoring request, publish a request object to the request topic listed above (glp/0/{SID}/=get/dp/request).
The response is published to a response endpoint indicated in the get request. There is exactly one response for each request. The response reports all values retrieved and reports one or more errors if all values could not be retrieved.
To cancel an on-demand datapoint monitoring request, publish a cancellation object to the cancel topic listed above (glp/0/{SID}/=get/dp/cancel). The cancellation object is the same as the request object, but only the corr property is required. All other properties are ignored. All pending requests with the same correlator are cancelled and complete with an error response for items not yet retrieved.
On-Demand Datapoint Monitoring Request
The request object has the following properties:
| Field Name | Type | Description | |
|---|---|---|---|
| corr | any | (Optional) The correlator. A verbatim copy is included with the response, if a correlator is provided. | |
| response | String | (Optional) The topic for the response publication. This is an absolute topic (not relative to the feedback or another IAP/MQ channel) allocated by the requester. If this property is omitted, the default response topic is set to | |
| item | String or list of strings | (Required) The item property specifies a single item or a list of items to be retrieved. Each item is a datapoint reference relative to the IAP/MQ feedback channel within the segment addressed with the on-demand monitoring request.
An empty item list serves no purpose but is permitted. An empty result list will be returned immediately. Items that cannot yield a response, yield an error. For example, one implementation of the on-demand monitoring service might not support on-demand monitoring through groups. It would report all other result values, and an error for the item addressed through a group. | |
| maxAge | Number | (Optional) The maxAge argument allows you to specify an acceptable cached value age in seconds. For example, if the targeted datapoint has been retrieved 3 seconds before this request, and maxAge states an acceptable age of 10 seconds, the cached value can be returned. However, when maxAge limits an acceptable maximum age of 1 second, the cached value would be discarded, and a fresh value would be obtained from the edge device. maxAge is optional and defaults to zero, which always discards a cached value regardless of its age. | |
| timeout | Number | (Optional) An optional timeout value can be provided. This timeout value defines the largest acceptable duration until the request must complete with success, partial error, or complete error. A partial error occurs when some, but not all, requested items are retrieved. This value provides the largest acceptable timeout value, but the on-demand monitoring service negotiates the actual timeout value with the edge processors and services involved to ensure that the request completes as soon as possible, even if it completes with a timeout error. When a timeout value is not included in the request, the timeout is unbounded, but it is finite and subject to negotiation with the edge processors and services involved. |
On-Demand Datapoint Monitoring Response
The response object is published to the response topic requested with the request, always using QoS=1, retain=False.
The response has the following properties:
| Field Name | Type | Description |
|---|---|---|
| corr | any | A verbatim copy of the request correlator, if any was provided. |
| result | Result object or list of result objects | Result object if the requested item was a single item, or list, or result objects if the requested item was a list of items. Each result object has an item property, which copies the item value from the request. Each result object has an error or a value property. The presence of a value indicates success, and the property reports the value retrieved. The presence of an error property indicates failure, and the property reports the nature of the failure, such as “timeout” or “not found” and so on. Example: |
On-Demand Monitoring Service Collaboration
The API is implemented in collaboration between an on-demand monitoring service and those edge processors and services that the on-demand monitoring service supports. The service receives a request, instructs the edge processor or service in charge of each item to retrieve that single item, assembles, and returns the response object to the caller when the response property is set in the request. If the response property is omitted, the service publishes the request to the individual driver in order to retrieve the item. The driver then directly publishes it to the events channel with the payload format that conforms to the event channel data.
The individual edge processors and services handle one item at a time. Aggregation of multiple items into one response is the responsibility of the on-demand monitoring service.
To request an individual item from an edge processor, the on-demand monitoring service publishes the Item poll request object at this topic:
| glp/0/./=engine/P/rq/poll/{Item} |
Where:
- P is the protocol identifier
- Item is the item as specified with the on-demand monitoring request.
When the response property in the request is omitted, the service forwards the request to the individual drivers on the topic.
Item Poll Request
The Item poll request object has the following properties:
| Field Name | Type | Description |
|---|---|---|
| corr | any | A verbatim copy of the request correlator, if any was provided. |
| respond | string | A response topic, allocated by the on-demand monitoring service. This property is set to a blank string when the response property in the request is omitted. |
| timeout | Number | A suggested timeout, in seconds. If present, timeout indicates that the operation is still in progress but advises on a better timeout value than the value provided with the request. This represents the edge processor’s best estimate and may be less or may be more than the timeout value provided with the item poll request object. The on-demand monitoring service evaluates this recommendation, adjusts its expectations accordingly, but adheres to the maximum timeout duration provided with the on-demand monitoring request, if such a value was provided. |
Item Poll Response
The Item poll response object has the following properties:
| Field Name | Type | Description |
|---|---|---|
| corr | any | A verbatim copy of the request correlator, if any was provided. |
| timeout | Number | An estimated timeout duration based on the edge processor’s knowledge of edge protocol capabilities. The response returns only one of the three properties: timeout, error, or value. See description of timeout in the Item poll request object table above. |
| error | string | value, if present, indicates successful completion and provides the datapoint value. The response returns only one of the three properties: timeout, error, or value. Example: "Not found" |
| value | any | error, if present, indicates unsuccessful completion and provides a human-readable error description. The response returns only one of the three properties: timeout, error, or value. Example: |