Version: 1.0
Status: ⚫⚫⚫
Monitor plugin for WPEFramework.
This document describes purpose and functionality of the Monitor plugin. It includes detailed specification of its configuration, methods provided and notifications sent.
All identifiers on the interface described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.
The table below provides and overview of acronyms used in this document and their definitions.
| Acronym | Description |
|---|---|
| API | Application Programming Interface |
| HTTP | Hypertext Transfer Protocol |
| JSON | JavaScript Object Notation; a data interchange format |
| JSON-RPC | A remote procedure call protocol encoded in JSON |
The table below provides and overview of terms and abbreviations used in this document and their definitions.
| Term | Description |
|---|---|
| callsign | The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique. |
| Ref ID | Description |
|---|---|
| HTTP | HTTP specification |
| JSON-RPC | JSON-RPC 2.0 specification |
| JSON | JSON specification |
| WPEF | WPEFramework API Reference |
The Monitor plugin provides a watchdog-like functionality for framework processes.
The plugin is designed to be loaded and executed within the WPEFramework. For more information on WPEFramework refer to [WPEF].
The table below lists configuration options of the plugin.
| Name | Type | Description |
|---|---|---|
| callsign | string | Plugin instance name (default: Monitor) |
| classname | string | Class name: Monitor |
| locator | string | Library name: libWPEFrameworkMonitor.so |
| autostart | boolean | Determines if the plugin is to be started automatically along with the framework |
The following methods are provided by the Monitor plugin:
Monitor interface methods:
| Method | Description |
|---|---|
| status | Returns the memory and process statistics either for a single plugin or all plugins watched by the Monitor |
| resetstats | Resets memory and process statistics for a single plugin watched by the Monitor |
| restartlimits | Sets new restart limits for a plugin |
Returns the memory and process statistics either for a single plugin or all plugins watched by the Monitor
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | The callsing of a plugin to get measurements snapshot of, if set empty then all observed objects will be returned |
| Name | Type | Description |
|---|---|---|
| result | array | |
| result[#] | object | |
| result[#].measurements | object | Measurements for the plugin |
| result[#].measurements.resident | object | Resident memory measurement |
| result[#].measurements.resident.min | number | Minimal value measured |
| result[#].measurements.resident.max | number | Maximal value measured |
| result[#].measurements.resident.average | number | Average of all measurements |
| result[#].measurements.resident.last | number | Last measured value |
| result[#].measurements.allocated | object | Allocated memory measurement |
| result[#].measurements.allocated.min | number | Minimal value measured |
| result[#].measurements.allocated.max | number | Maximal value measured |
| result[#].measurements.allocated.average | number | Average of all measurements |
| result[#].measurements.allocated.last | number | Last measured value |
| result[#].measurements.shared | object | Shared memory measurement |
| result[#].measurements.shared.min | number | Minimal value measured |
| result[#].measurements.shared.max | number | Maximal value measured |
| result[#].measurements.shared.average | number | Average of all measurements |
| result[#].measurements.shared.last | number | Last measured value |
| result[#].measurements.process | object | Processes measurement |
| result[#].measurements.process.min | number | Minimal value measured |
| result[#].measurements.process.max | number | Maximal value measured |
| result[#].measurements.process.average | number | Average of all measurements |
| result[#].measurements.process.last | number | Last measured value |
| result[#].measurements.operational | boolean | Whether the plugin is up and running |
| result[#].measurements.count | number | Number of measurements |
| result[#].observable | string | A callsign of the watched plugin |
| result[#].memoryrestartsettings | object | Restart limits for memory consumption related failures applying to the plugin |
| result[#].memoryrestartsettings.limit | number | Maximum number or restarts to be attempted |
| result[#].memoryrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
| result[#].operationalrestartsettings | object | Restart limits for stability failures applying to the plugin |
| result[#].operationalrestartsettings.limit | number | Maximum number or restarts to be attempted |
| result[#].operationalrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
{
"jsonrpc": "2.0",
"id": 1234567890,
"method": "Monitor.1.status",
"params": {
"callsign": ""
}
}{
"jsonrpc": "2.0",
"id": 1234567890,
"result": [
{
"measurements": {
"resident": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"allocated": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"shared": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"process": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"operational": true,
"count": 100
},
"observable": "callsign",
"memoryrestartsettings": {
"limit": 3,
"windowseconds": 60
},
"operationalrestartsettings": {
"limit": 3,
"windowseconds": 60
}
}
]
}Resets memory and process statistics for a single plugin watched by the Monitor
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | The callsign of a plugin to reset statistics of |
| Name | Type | Description |
|---|---|---|
| result | object | Measurements for the plugin before reset |
| result.measurements | object | Measurements for the plugin |
| result.measurements.resident | object | Resident memory measurement |
| result.measurements.resident.min | number | Minimal value measured |
| result.measurements.resident.max | number | Maximal value measured |
| result.measurements.resident.average | number | Average of all measurements |
| result.measurements.resident.last | number | Last measured value |
| result.measurements.allocated | object | Allocated memory measurement |
| result.measurements.allocated.min | number | Minimal value measured |
| result.measurements.allocated.max | number | Maximal value measured |
| result.measurements.allocated.average | number | Average of all measurements |
| result.measurements.allocated.last | number | Last measured value |
| result.measurements.shared | object | Shared memory measurement |
| result.measurements.shared.min | number | Minimal value measured |
| result.measurements.shared.max | number | Maximal value measured |
| result.measurements.shared.average | number | Average of all measurements |
| result.measurements.shared.last | number | Last measured value |
| result.measurements.process | object | Processes measurement |
| result.measurements.process.min | number | Minimal value measured |
| result.measurements.process.max | number | Maximal value measured |
| result.measurements.process.average | number | Average of all measurements |
| result.measurements.process.last | number | Last measured value |
| result.measurements.operational | boolean | Whether the plugin is up and running |
| result.measurements.count | number | Number of measurements |
| result.observable | string | A callsign of the watched plugin |
| result.memoryrestartsettings | object | Restart limits for memory consumption related failures applying to the plugin |
| result.memoryrestartsettings.limit | number | Maximum number or restarts to be attempted |
| result.memoryrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
| result.operationalrestartsettings | object | Restart limits for stability failures applying to the plugin |
| result.operationalrestartsettings.limit | number | Maximum number or restarts to be attempted |
| result.operationalrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
{
"jsonrpc": "2.0",
"id": 1234567890,
"method": "Monitor.1.resetstats",
"params": {
"callsign": "WebServer"
}
}{
"jsonrpc": "2.0",
"id": 1234567890,
"result": {
"measurements": {
"resident": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"allocated": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"shared": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"process": {
"min": 0,
"max": 100,
"average": 50,
"last": 100
},
"operational": true,
"count": 100
},
"observable": "callsign",
"memoryrestartsettings": {
"limit": 3,
"windowseconds": 60
},
"operationalrestartsettings": {
"limit": 3,
"windowseconds": 60
}
}
}Sets new restart limits for a plugin
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | The callsign of a plugin to reset measurements snapshot for |
| params.operationalrestartsettings | object | Restart setting for memory consumption type of failures |
| params.operationalrestartsettings.limit | number | Maximum number or restarts to be attempted |
| params.operationalrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
| params.memoryrestartsettings | object | Restart setting for stability type of failures |
| params.memoryrestartsettings.limit | number | Maximum number or restarts to be attempted |
| params.memoryrestartsettings.windowseconds | number | Time period within which failures must happen for the limit to be considered crossed |
| Name | Type | Description |
|---|---|---|
| result | null | Always null |
{
"jsonrpc": "2.0",
"id": 1234567890,
"method": "Monitor.1.restartlimits",
"params": {
"callsign": "WebServer",
"operationalrestartsettings": {
"limit": 3,
"windowseconds": 60
},
"memoryrestartsettings": {
"limit": 3,
"windowseconds": 60
}
}
}{
"jsonrpc": "2.0",
"id": 1234567890,
"result": null
}Notifications are autonomous events, triggered by the internals of the plugin, and broadcasted via JSON-RPC to all registered observers. Refer to [WPEF] for information on how to register for a notification.
The following events are provided by the Monitor plugin:
Monitor interface events:
| Event | Description |
|---|---|
| action | Signals action taken by the monitor |
Signals action taken by the monitor
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | Callsign of the plugin the monitor acted upon |
| params.action | string | The action executed by the monitor on a plugin. (must be one of the following: Activate, Deactivate, StoppedRestarting) |
| params.reason | string | A message describing the reason the action was taken of |
{
"jsonrpc": "2.0",
"method": "client.events.1.action",
"params": {
"callsign": "WebServer",
"action": "Deactivate",
"reason": "EXCEEDED_MEMORY"
}
}