Version: 1.0
Status: ⚫⚫⚫
Monitor plugin for Thunder framework.
This document describes purpose and functionality of the Monitor plugin. It includes detailed specification of its configuration, methods and properties provided, as well as 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 |
| Thunder | Thunder API Reference |
The Monitor plugin provides a watchdog-like functionality for framework processes.
The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].
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 |
|---|---|
| restartlimits | Sets new restart limits for a service |
| resetstats | Resets memory and process statistics for a single service watched by the Monitor |
Sets new restart limits for a service.
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | The callsign of a service to reset measurements snapshot of |
| params.operational | object | Restart settings for memory consumption type of failures |
| params.operational.limit | number | Maximum number or restarts to be attempted |
| params.operational.window | number | Time period within which failures must happen for the limit to be considered crossed |
| params.memory | object | Restart settings for stability type of failures |
| params.memory.limit | number | Maximum number or restarts to be attempted |
| params.memory.window | 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",
"operational": {
"limit": 3,
"window": 60
},
"memory": {
"limit": 3,
"window": 60
}
}
}{
"jsonrpc": "2.0",
"id": 1234567890,
"result": null
}Resets memory and process statistics for a single service watched by the Monitor.
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | The callsign of a service to reset statistics of |
| Name | Type | Description |
|---|---|---|
| result | object | Measurements for the service before reset |
| result.measurements | object | Measurements for the service |
| 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 service is up and running |
| result.measurements.count | number | Number of measurements |
| result.observable | string | A callsign of the watched service |
| result?.restart | object | (optional) Restart limits for memory/operational failures applying to the service |
| result?.restart?.memory | object | (optional) Restart limits for memory consumption related failures applying to the service |
| result?.restart?.memory.limit | number | Maximum number or restarts to be attempted |
| result?.restart?.memory.window | number | Time period within which failures must happen for the limit to be considered crossed |
| result?.restart?.operational | object | (optional) Restart limits for stability failures applying to the service |
| result?.restart?.operational.limit | number | Maximum number or restarts to be attempted |
| result?.restart?.operational.window | 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",
"restart": {
"memory": {
"limit": 3,
"window": 60
},
"operational": {
"limit": 3,
"window": 60
}
}
}
}The following properties are provided by the Monitor plugin:
Monitor interface properties:
| Property | Description |
|---|---|
| status RO | Service statistics |
Provides access to the service statistics.
This property is read-only.
| Name | Type | Description |
|---|---|---|
| (property) | array | Service statistics |
| (property)[#] | object | |
| (property)[#].measurements | object | Measurements for the service |
| (property)[#].measurements.resident | object | Resident memory measurement |
| (property)[#].measurements.resident.min | number | Minimal value measured |
| (property)[#].measurements.resident.max | number | Maximal value measured |
| (property)[#].measurements.resident.average | number | Average of all measurements |
| (property)[#].measurements.resident.last | number | Last measured value |
| (property)[#].measurements.allocated | object | Allocated memory measurement |
| (property)[#].measurements.allocated.min | number | Minimal value measured |
| (property)[#].measurements.allocated.max | number | Maximal value measured |
| (property)[#].measurements.allocated.average | number | Average of all measurements |
| (property)[#].measurements.allocated.last | number | Last measured value |
| (property)[#].measurements.shared | object | Shared memory measurement |
| (property)[#].measurements.shared.min | number | Minimal value measured |
| (property)[#].measurements.shared.max | number | Maximal value measured |
| (property)[#].measurements.shared.average | number | Average of all measurements |
| (property)[#].measurements.shared.last | number | Last measured value |
| (property)[#].measurements.process | object | Processes measurement |
| (property)[#].measurements.process.min | number | Minimal value measured |
| (property)[#].measurements.process.max | number | Maximal value measured |
| (property)[#].measurements.process.average | number | Average of all measurements |
| (property)[#].measurements.process.last | number | Last measured value |
| (property)[#].measurements.operational | boolean | Whether the service is up and running |
| (property)[#].measurements.count | number | Number of measurements |
| (property)[#].observable | string | A callsign of the watched service |
| (property)[#]?.restart | object | (optional) Restart limits for memory/operational failures applying to the service |
| (property)[#]?.restart?.memory | object | (optional) Restart limits for memory consumption related failures applying to the service |
| (property)[#]?.restart?.memory.limit | number | Maximum number or restarts to be attempted |
| (property)[#]?.restart?.memory.window | number | Time period within which failures must happen for the limit to be considered crossed |
| (property)[#]?.restart?.operational | object | (optional) Restart limits for stability failures applying to the service |
| (property)[#]?.restart?.operational.limit | number | Maximum number or restarts to be attempted |
| (property)[#]?.restart?.operational.window | number | Time period within which failures must happen for the limit to be considered crossed |
The callsign shall be passed as the index to the property, e.g. Monitor.1.status@WebServer. If omitted then all observed objects will be returned on read.
{
"jsonrpc": "2.0",
"id": 1234567890,
"method": "Monitor.1.status@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",
"restart": {
"memory": {
"limit": 3,
"window": 60
},
"operational": {
"limit": 3,
"window": 60
}
}
}
]
}Notifications are autonomous events, triggered by the internals of the plugin, and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] 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 an action taken by the Monitor |
Signals an action taken by the Monitor.
| Name | Type | Description |
|---|---|---|
| params | object | |
| params.callsign | string | Callsign of the service the Monitor acted upon |
| params.action | string | The action executed by the Monitor on a service. One of: "Activate", "Deactivate", "StoppedRestarting" |
| params.reason | string | A message describing the reason the action was taken |
{
"jsonrpc": "2.0",
"method": "client.events.1.action",
"params": {
"callsign": "WebServer",
"action": "Deactivate",
"reason": "EXCEEDED_MEMORY"
}
}