Plugin simulator

This guide briefly describes the oneagent_simulate_plugin command line tool. The plugin simulator enables you to quickly test your code without deploying OneAgent and/or upload plugins to Dynatrace Cluster Node.

A typical plugin simulator workflow might proceed 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.

Command syntax

The options are available by issuing the oneagent_simulate_plugin --help or oneagent_sim --help command:

usage: oneagent_simulate_plugin [-h] [-p PLUGIN_DIR] [-v] [-s 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
  -s 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

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. This later 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.

Snapshot file

This is the path to a JSON file that contains the process snapshot. The plugin simulator uses this information to determine whether it can test the plugin.

The structure of the simulator_snapshot.json file resembles ProcessSnapshot, where fields that are not required for testing the plugin are set to default values. An example snapshot might look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "entries": [
    {
      "process_type": 29,
      "group_name": "oneagent_sdk.demo_app_auth",
      "processes": [
        {
          "process_name": "python3.5",
          "properties": {
            "CmdLine": "-m oneagent_sdk.demo_app_auth",
            "WorkDir": "/home/demo",
            "ListeningPorts": "8779"
          }
        }
      ]
    }
  ]
}

Properties file

If your plugin requires configuration, use a JSON file that contains a dictionary of properties and their values. Here's an example:

1
2
3
4
{
  "user": "ruxit",
  "password": "ruxit"
}

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 results (for example, if it computes differences or averages between consecutive measurements).

Limitations

Current limitations of the plugin simulator are:

  • Process snapshot must be created manually
  • Plugin properties must be created manually
  • There is currently no means of testing visualization of plugin measurements
  • The simulator uses the Python interpreter and environment that you provide. It doesn't install libraries, even when they're required by the plugin.