Extension simulator

Extensions 1.0 end of life

OneAgent and ActiveGate version 1.299 are the last versions supporting OneAgent and ActiveGate Extensions 1.0 framework. You can continue using Extensions 1.0 if you stay at OneAgent or ActiveGate version 1.299. Note that this means you'll be using an unsupported Python version 3.8. We strongly recommend migrating your extensions to the latest Extensions 2.0 framework.

For more information, see General guidance and how to migrate.

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

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

A typical extension simulator workflow is as follows:

  1. Write the extension code and plugin.json.
  2. Create a simulator_snapshot.json file with the minimum data required to trigger extension activation.
  3. Create a properties.json file with the configuration properties required by your extension.
  4. Run the extension 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 extension. 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

Extension directory

To point to the extension directory, use the -p or --plugin_dir parameters. This is the path to the directory that contains the extension you're testing. The extension 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 extension, 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 extension depends on. However, it also requires that you run the build command for syncing.

Properties file

If your extension 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 extension:

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

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

Interval

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

Analyze the extension 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 extension 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.