Monitoring Preference Object

rate

number

Sets a monitoring rate (in seconds) or requests a monitoring method.

rate = N, if N is greater than zero, enables periodic acquisition of the value at the specified rate. A value of zero disables periodic value acquisition. The specified rate is a desired rate, but delivery of datapoint monitoring events is not guaranteed to occur at that rate, subject to the overall system load, edge network capabilities, topology, size and other factors.
NOTE: This number can specify fractions of seconds, but the edge processor might round or truncate that number to the nearest number that it can support.

rate can also request an abstract poll rate with string values slow, normal, or fast, where the edge protocol processor chooses an appropriate rate based on its knowledge of the edge protocol and available resources.

rate can be null, 0 (zero), or the string none. All these indicate that monitoring is not enabled for this datapoint.

(Optional) The presence of the event property indicates support for event-based monitoring. When present, event can be true or false. The default is event: false. Setting event to true enables event-based monitoring.

Event-driven monitoring obtains values as they are reported, and not usually at a deterministic rate.

On some edge protocols, event-driven monitoring has higher cost in the creation but lower running cost compared to periodic sampling.

A third method is known as on-demand monitoring.

All three monitoring methods can be combined, but only periodic sampling and event-driven monitoring share the same filter controls, such as threshold and throttle.

Not all edge protocols can support event-based monitoring. Protocol engines that cannot support event-based monitoring do not report the event property with the monitor control object.

report

string

Controls whether any captured value is reported, or only whether a change occurred, possibly subject to additional conditions. Possible report values:

throttle

number

throttle is a timer to slow down event generation.

If a value qualifies for publication, subject to focus, report and threshold properties, throttle: T gives a number of seconds (T). Datapoint monitoring events are not published more often than once in T seconds. The heartbeat timer can override the throttle.

Object or Number

(Optional) The minimum change required to qualify for reporting the new captured value. threshold can be 0 (zero), null or undefined to disable threshold filtering.

The threshold property applies to datapoints implementing numbers and those of complex types that include numbers. A distance between values of other data types such as Boolean values or strings is not defined and threshold is ignored in those cases.

For datapoints implementing simple numbers, the threshold defines the minimum absolute value difference required to qualify for publication.

For datapoints with complex values, threshold takes an object that mirrors the datapoint value. For example, consider this hypothetical datapoint value example:

This example defines thresholds of 2 for the three point coordinates x, y and z, and a threshold of 5 for speed. range has no threshold, permitting any new range value to be reported. The string-typed property mode cannot support a threshold.

Threshold specifications can only apply to numeric datapoints or numeric fields within complex datapoints. Thresholds are always unsigned numbers as they define the unsigned (absolute) difference between the current and the most recently reported value.

focus

String

(Optional) A directive to focus on a specific field within a complex type. focus can be null or undefined to disable the focus feature.

focus can be a string containing a property path within a complex data type, separated by / to address nested properties. This focuses monitoring on the selected field (which itself can be a complex type).

When a focus is specified, all reporting and all evaluations of throttle, report, and threshold specifications ignore all except for the property in focus. The resultant data report only contains the focused field.

For example, focus = "speed" examines and reports only the "speed" field from the example in threshold, focus = “point/z” examines and reports only the z coordinate from the same example.

cat

string

(Optional) Controls the event category for reports. cat is described in the properties table in Events.

Default is “data.”

inFeedback

Boolean

(Optional) Controls whether values captured with monitoring must also update the feedback channel.

Default is “True”.

heartbeat

(Optional)  heartbeat is a timer to ensure event generation.  If a value does not qualify for publication subject to focus, report, threshold and throttle preferences, heartbeat: H specifies a number of seconds H. A monitoring event is published at least once every H seconds, providing a minimum monitoring event rate.

heartbeat has higher priority than all other filters. An event is reported based on a heartbeat expiration, even if the value does not otherwise qualify. The heartbeat value is always the most recently obtained value.

The heartbeat interval can be set to zero to disable the heartbeat.

(Optional) Indicates the health of the datapoint. This value is updated whenever the health of the datapoint changes. 

Possible values are:  normal or down.

See receiveTimeout below for detail. 

(Optional) A receive timeout value, in seconds, or 0 to disable a receive timeout. This is used with input datapoints on locally hosted (virtual) devices or with remote output datapoints that are monitored with event: true. When the receive timeout expires before a value has been received from the datapoint, the datapoint is reported with health: down until another value is received. 

This can be used to monitor remote data and monitor basic communications quality at once. 

Edge drivers that do not support this tool do not report it in the feedback.