ActiveGate Plugin Simulator

To facilitate plugin development, ActiveGate Plugins SDK comes with a tool that can execute your plugin without the need for you to run an ActiveGate or connect to DESK Server. This plugin simulator is a pure Python solution that's designed to mimic ActiveGate with only a few limitations:

  • Plugin configuration (if any) needs to be provided manually in the form of a JSON file.
  • No data is sent to or received from DESK Server.
  • The Python environment contains the libraries required by the plugin.

A typical plugin simulator workflow is as follows:

  1. Write the plugin code and plugin.json.
  2. Create a simulator_snapshot.json file with the minimum data required to trigger plugin activation.
  3. Create a properties.json file with the configuration properties required by your plugin.
  4. Run the plugin simulator and observe the reported results. Address any identified errors.

Run the simulator

To start the simulator, use the following command:

oneagent_simulate_plugin

Or shorter:

oneagent_sim

No additional arguments are needed if the command is executed from the directory that contains the plugin. For other options, see below.

(sdk) c:\work\plugin_development\custom.remote.python.stress>oneagent_sim --help
usage: oneagent_sim [-h] [-p PLUGIN_DIR] [-v] [-n SNAPSHOT] [-r PROPERTIES]
                    [-i INTERVAL] [--version]

optional arguments:
  -h, --help            show this help message and exit
  -p PLUGIN_DIR, --plugin_dir PLUGIN_DIR
                        plugin directory path
  -v, --verbose         increase verbosity
  -n SNAPSHOT, --snapshot SNAPSHOT
                        path to snapshot file
                        (PLUGIN_DIR/simulator_snapshot.json by default)
  -r PROPERTIES, --properties PROPERTIES
                        path to properties file (PLUGIN_DIR/properties.json by
                        default)
  -i INTERVAL, --interval INTERVAL
                        set the interval between plugin measurements (default:
                        60 seconds)
  --version             show program's version and exit

Plugin directory

To point to the plugin directory, use the -p or --plugin_dir parameters. This is the path to the directory that contains the plugin you're testing. The plugin directory path must contain the plugin.json file, which will be added to the Python module search path. You can set this to the path where you're developing your plugin, or you can set it to the output of the oneagent_build_plugin command. The latter approach has the advantage of immediately providing the libraries that your plugin depends on. However, it also requires that you run the build command for syncing.

Properties file

If your plugin requires configuration, use a JSON file that contains a dictionary of properties and their values. See an example of the properties.json that must be saved in the directory that contains the developed plugin:

{
  "url": "http://localhost:8769",
  "user": "ruxit",
  "password": "ruxit"
}

The configuration corresponds to the properties section in plugin.json (see ActiveGate plugins reference).

Interval

The plugin simulator can also change the interval between measurements. This can be useful for calling methods at a higher frequency, or when your plugin requires multiple measurements to send the results. For example, if it computes differences or averages between consecutive measurements.

Analyze the plugin simulator screen output

The simulator runs until it is stopped manually (usually by pressing Ctrl-C). The output is written to the terminal and log file, and a short summary of operations is provided upon completion, which should look similar to:

INFO:plugin_development.global:{('custom.remote.python.demo', '123'): (PluginState(pluginName='custom.remote.python.demo', pluginVersion='1.0', state='OK', description='', monitoredEntityId='123', stacktrace=''), 242022.234)}
WARNING:plugin_sdk.plugin_simulator:Plugin simulator was stopped with a Keyboard interrupt                                                                                                                                        
Plugin simulator summary:                                                                                                                                                                                                         
At 10:03:30 reported measurements:                                                                                                                                                                                                
[WrappedPluginMeasurement(monitoredEntityId=8410346495561112286, tsIdentifier='custom.remote.python.demo:countercd', dimensions=[], value=2.0, aggregation=1, isV3=False, isStatetimeseries=False, isStatCounter=False),          
 WrappedPluginMeasurement(monitoredEntityId=837416055638757496, tsIdentifier='custom.remote.python.demo:countercd', dimensions=[], value=2.0, aggregation=1, isV3=False, isStatetimeseries=False, isStatCounter=False)]           
At 10:03:30 reported status: OK

If an error occurs, the summary may offer a hint as to why:

Plugin simulator summary:
At 10:05:17 reported status: UNINITIALIZED
At 10:05:17 reported status: ERROR_UNKNOWN
Status details:
HTTPConnectionPool(host='localhost', port=8769): Max retries exceeded with url: /topology (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x00000275168A3E48>: Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it',))

In this example, the error was caused by the absence of a running oneagent_sdk.demo_app process. So the plugin was unable to gather data.

The report at the end of the simulator run isn't the only source of information. You can also analyze log messages that are sent while the simulator runs.