Monitor
Use the Monitor web service to monitor Remote Manager activity and push notifications to a client application. Each configured monitor specifies the Remote Manager events or activities to monitor, the notification mechanism, and the transport type (TCP, HTTP, or Polling).
Monitored events can include:
- Data: Data pushed into Remote Manager from remote gateways in the form of DataPoints (directly or through DIA or Smart Energy), FileData, and so on.
- Status: General status updates such as connection status or remote device availability.
- Alarms: Alarm status updates, such as when alarms are triggered or reset.
FileData and FileDataCore events are not published when the file size is larger than 120K. Delete operations for FileData events are never published.
The Monitor web service is available only for Remote Manager accounts with a subscription to the Push Monitor service.
For information on retrieving saved pushed notifications or resetting a monitor, see v1/monitors.
URI
http://<hostname>/ws/Monitor
Formats
HTTP method | Format | Description |
---|---|---|
GET | /ws/Monitor | Get a list of all configured monitors. |
GET | /ws/Monitor/{monId} | Get details for a specific monitor. |
POST | /ws/Monitor | Create a new monitor to push event notifications. |
PUT | /ws/Monitor/{monId} | Update an existing monitor. Note that any PUT request to a monitor resets the monitor state. |
DELETE | /ws/Monitor/{monId} | Delete a monitor. |
Elements
monId
System-generated identifier for the monitor.
cstId
Remote Manager identifier for the customer.
monFormatType
Format for delivered event data:
- xml
- json
monTopic
One or more topics to monitor. Supported monitor topics include:
-
alert_status
-
devices
-
jobs
-
Alarm
-
AlarmStatus
-
DataPoint
-
DataStream
-
DeviceCore
-
FileData
-
FileDataCore
-
Job
-
JobResult
-
XbeeCore
The following monitor topics have been deprecated and should not be used: DiaChannelDataFull, XbeeAttributeDataCore, XbeeEventDataCore.
FileData and FileDataCore events are not published when the file size is larger than 120K. Delete operations for FileData events are not published.
DataStream updates publish changes to DataStream attributes only, not currentValues. To get changes for currentValue, monitor the DataPoint topic to get changes to the current value as they arrive.
To monitor | Specify |
---|---|
general topic | Resource name only. For example:DataPoint Monitors all DataPoint events. |
specific resource | Resource name followed by the resource ID using standard REST slash conventions. For example:DataPoint/00000000-00000000-00000000-00000000 Monitors DataPoint events reported by the specific device. |
multiple topics | Comma-delimited list of topics. For example:DataPoint,DeviceCore Monitors all DataPoint and Device data for the current customer. |
scope by operation | By default, all operations for the specified monitor topic are monitored. To limit the monitor topic to specific operations, prefix the monitor topic with the operation qualifier. Valid operations:C for createU for any updateD for deleteFor example, to monitor update operations only for DeviceCore:[operation=U]DeviceCore To monitor create and update operations for DeviceCore:[operation=C,U]DeviceCore |
scope by group | By default, all groups for the specified monitor topic are monitored. To limit the monitor topic to one or more groups, prefix the monitor topic with the group qualifier. For example:[group=America,Columbia]DeviceCore |
scope by operation and group | To use both the operation and the group qualifiers, prefix the monitor topic with both qualifiers:[operation=C,U,D][group=America,Columbia]DeviceCore Note You can prefix the qualifiers in any order. |
special characters | URL encode the following special characters when specifying additional subtopic components:/ (forward slash)% (percent sign). (period)* (asterisk)[ (open bracket)] (close bracket)When monitor topics are reported, components are URL encoded. This allows for easy parsing of monitor topics. The general procedure is to split the published topic string on the backslash (/) separator character and then URL decode the identified components. |
monTransportHeaders
For HTTP transport type only. HTTP header fields in the following format:
header-name: header-value
header-name-2: header-value-2
Returned in the GET response. Returned as a comma separated list of header names.
monTransportType
Transport method used to deliver push notifications to the client application:
- tcp: Push notifications are sent using TCP. See TCP transport protocol.
- http: Push notifications are sent using HTTP. See HTTP/HTTPS transport protocol.
- polling: Push notifications are saved but not sent. See v1/monitors for information on retrieving polling monitor notifications.
monTransportUrl
For HTTP transport type only. URL of the customer web server. For http URLs, the default listening port is 80; for https URLs, the default listening port is 443.
monTransportToken
For HTTP transport type only. Credentials for basic authentication in the following format:
username:password
monTransportMethod
For HTTP transport type only. HTTP method to use for sending data: PUT or POST. The default is PUT.
monConnectTimeout
For HTTP transport type only. Time in milliseconds Remote Manager waits when attempting to connect to the destination http server. A value of 0 means use the system default of 5000 (5 seconds). Most monitors do not need to configure this setting.
monResponseTimeout
For HTTP transport type only. Time in milliseconds Remote Manager waits for a response for pushed events from the http server. A value of 0 means use the system default of 5000 (5 seconds). Most monitors do not need to configure this setting.
monAckOption
For TCP transport type only. Indicates whether the client will explicitly acknowledge TCP push events or allow Remote Manager to automatically acknowledge events when sent. Options include: explicit or off. The default is off.
monBatchSize
Specifies an upper bound on how many messages are aggregated before sending a batch. The default is 100.
monBatchDuration
Specifies an upper bound on the number of seconds messages are aggregated before sending. The default is 10.
monCompression
Keyword that specifies the method used to compress messages. Options include: zlib or none. The default is none. For zlib, the deflate algorithm is used to compress the data; use inflate to decompress the data.
Note For backwards compatibility, gzip is accepted as a valid keyword. Compression has always been done using the deflate algorithm.
monAutoReplayOnConnect
Boolean value that specifies whether Remote Manager replays any missed published events before any new published events are forwarded. True indicates missed published events are replayed. False indicates missed published events are not replayed. The default is false.
monDescription
Optional text field used to label or describe the monitor.
monLastConnect
Returned in the GET response. Specifies last connection time to the client application.
monLastSent
Returned in the GET response. Specifies the last message pushed to the client application.
monStatus
Returned in the GET response. Specifies the current connection status to the client application.
Status | Description |
---|---|
CONNECTING | For HTTP monitors only. Remote Manager is attempting to connect to the configured HTTP server. Once connected, the state changes to ACTIVE. |
ACTIVE | Monitor is connected and publishing events. |
INACTIVE | Monitor is not connected and events are not published or recorded. |
SUSPENDED | For monitors with monAutoReplayOnConnect = True.Monitor has disconnected, but publish events are recorded for later replay. |
DISABLED | For HTTP monitors only. If a monitor has not connected for 24 hours, the state is set to DISABLED, and publish events are not recorded for replay. A disabled monitor must be reconfigured via the Monitor web service. |
DISCONNECT | Monitor is currently disconnecting, and events are not being published. For monitors with monAutoReplayOnConnect = True, events are recorded for later replay. (Dashboard shows status as Disconnecting.) |
Any PUT request to a monitor resets the monitor state.