Install Plugins SDK

The ActiveGate Plugins SDK provides you with all the resources and means necessary to develop your own ActiveGate plugins. To get started with the ActiveGate Plugin SDK, follow the steps below.

Download

Sign in to Dynatrace and go to Settings > Monitored technologies > Add new technology monitoring > Add ActiveGate plugin > Download Plugin SDK Add new technology button Add ActiveGate plugin button Download SDK button

Extract the downloaded ZIP file. It contains docs, examples, and the whl file that's required for installation (for example, plugin_sdk-1.156.0.20181003.61122-py3-none-any.whl).

Installation

You need the following to install the SDK:

  • ActiveGate plugin module installed and running on the Environment ActiveGate you'll use to run your plugins. ActiveGate version 1.175+ has the plugin module installed by default.
  • Python 3.6+ with PIP installed.

To install your downloaded SDK use:

pip3 install plugin_sdk-version.whl

For example:

pip3 install plugin_sdk-1.156.0.20181003.61122-py3-none-any.whl

SDK commands

The Plugin SDK contains a number of useful deployment and development tools provided in the form of command line Python scripts. This section describes all of the available commands.

The plugin_sdk command is a single entry point to all commands. It allows you to run all SDK commands using a single command.

(sdk) c:\work\plugin_development\custom.remote.python.stress>plugin_sdk --help
usage: plugin_sdk [-h] [--version]
                  {verify_plugin,build_plugin,upload_plugin,simulate_plugin,start_demo_app}
                  ...

Use one of the following arguments to invoke a certain command. See 'plugin_sdk
<command> --help' to read about specific commands.

positional arguments:
  {verify_plugin,build_plugin,upload_plugin,simulate_plugin,start_demo_app}
    verify_plugin       checks plugin.json
    build_plugin        builds plugin
    upload_plugin       uploads plugin zip
    simulate_plugin     starts plugin simulator
    start_demo_app      starts demo application

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version and exit

verify_plugin

The verify_plugin command verifies the validity of the plugin.json file. Use -p or --plugin_dir parameters to point to the file you want to verify.

usage: plugin_sdk [-h] [-p PLUGIN_DIR] [-v] [--version]

optional arguments:
  -h, --help            show this help message and exit
  -p PLUGIN_DIR, --plugin_dir PLUGIN_DIR
  -v, --verbose         increase verbosity
  --version             show program's version and exit

Sample result:

(sdk) c:\work\plugin_development\custom.remote.python.stress>plugin_sdk verify_plugin -p .
Arguments: ['C:\\work\\virtualenv\\sdk\\sdk\\Scripts\\plugin_sdk', '-p', '.']
Arguments=Namespace(plugin_dir='.', verbose=False)
Starting oneagent_verify_plugin
Checking plugin metadata: c:\work\plugin_development\custom.remote.python.stress\plugin.json
Validating plugin.json against schema
Plugin custom.remote.python.stress is valid

build_plugin

The build_plugin command builds the plugin package from the source code of any directory. The directory should contain at least the plugin.json and the Python script file (.py). Point to the directory using the -p or --plugin_dir parameters. Otherwise, the current directory will be used. The command creates the plugin package in the form of a ZIP file and saves it the deployment directory as defined by -d or --deployment_dir parameters. The deployment directory is automatically discovered if the plugin module is installed on the machine.

The plugin directory may contain some classified information like server tokens or passwords. Therefore, certain files aren't included in the build package. By default, files matching the following patterns are omitted:

  • token.conf
  • properties.json
  • simulator_snapshot.json
  • *.log
  • file_blacklist.txt

The list of omitted files may be extended by creating a file_blacklist.txt file in the plugin directory with list of patterns, in the following format:

token.conf
properties.json
simulator_snapshot.json
*.log
file_blacklist.txt

Ensure that none of your classified information is included in the plugin package because the package will be uploaded to the server, distributed among ActiveGate hosts, and stored in a code repository.

As the next step, oneagent_build_plugin attempts to upload the plugin package to the Dynatrace server. You need to provide the server URL and token to do this. Again, these will be automatically discovered if the plugin module is installed on the machine. Pay attention to the upload result. If it fails, you'll learn the reason from the command output.

usage: plugin_sdk [-h] [-p PLUGIN_DIR] [-d DEPLOYMENT_DIR] [-v] [--no_upload]
                  [--no_cert_ver] [--version]

optional arguments:
  -h, --help            show this help message and exit
  -p PLUGIN_DIR, --plugin_dir PLUGIN_DIR
                        plugin source directory
  -d DEPLOYMENT_DIR, --deployment_dir DEPLOYMENT_DIR
                        destination dir to deploy plugin
  -v, --verbose         increase verbosity
  --no_upload           turn off upload to the server
  --no_cert_ver         turn off ssl certificate verification
  --version             show program's version and exit

upload_plugin

The upload_plugin command uploads the plugin package to Dynatrace server. For details, refer to oneagent_build_plugin.

usage: plugin_sdk [-h] [-p PLUGIN_ZIP] [-v] [--no_cert_ver] [-s SERVER]
                  [-t TOKEN] [-T TOKEN_FILE]

optional arguments:
  -h, --help            show this help message and exit
  -p PLUGIN_ZIP, --plugin_zip PLUGIN_ZIP
                        plugin zip path (default location of
                        oneagent_build_plugin is taken by default)
  -v, --verbose         increase verbosity
  --no_cert_ver         turn off ssl certificate verification
  -s SERVER, --server SERVER
                        server address (taken from oneagent configuration file
                        by default)
  -t TOKEN, --token TOKEN
                        set the authentication token (token file is used if
                        token is not set)
  -T TOKEN_FILE, --token_file TOKEN_FILE
                        set the authentication token file (by default env
                        variable ONEAGENT_PLUGIN_UPLOAD_TOKEN, or
                        plugin_upload.token from configuration directory,
                        which is:
                        C:\ProgramData\dynatrace\remotepluginmodule\agent\conf
                        for remote plugin or:
                        C:\ProgramData\dynatrace\oneagent\agent\config for
                        local plugin, if env variable is not specified)

Example usage. Note the VALIDATION_ERROR_VERSION_CONFLICT error.

(sdk) c:\work\plugin_development\custom.remote.python.stress>plugin_sdk upload_plugin -p "c:\Program Files\dynatrace\remotepluginmodule\plugin_deployment\custom.remote.python.stress.zip"
Arguments: ['C:\\work\\virtualenv\\sdk\\sdk\\Scripts\\plugin_sdk', '-p', 'c:\\Program Files\\dynatrace\\remotepluginmodule\\plugin_deployment\\custom.remote.python.stress.zip']
reading token from file C:\Program Files\dynatrace\remotepluginmodule\agent\conf\plugin_upload.token
Attempting to send plugin to server https://hmk87980.dev.dynatracelabs.com:443/api/v1/remoteplugins
server https://hmk87980.dev.dynatracelabs.com:443/api/v1/remoteplugins/ returned status code: 400 {"error":{"code":400,"message":"VALIDATION_ERROR_VERSION_CONFLICT"}}
Please execute oneagent_verify_plugin before upload to validate plugin.json against the schema

simulate_plugin

The plugin_sdk simulate_plugin plugin simulator enables you to quickly test your code without deploying ActiveGate plugin module and/or upload plugins to Dynatrace server, so it can be run in the development environment.

For more information, see ActiveGate Plugin Simulator

Deployment

Once you've written your plugin, you can use the SDK to build it and upload it to the server. If you want to simply validate your plugin.json file type:

plugin_sdk build_plugin --no_upload

If you want to upload your plugin to the server, type:

plugin_sdk upload_plugin -t yourtoken

For your plugin development, you can also use the ActiveGate plugin simulator.

Troubleshooting

If after deploying your ActiveGate plugin the results are different from your expectations, check our troubleshooting information to find out what went wrong.

Configuration

Following successful deployment, you should see your plugin ready for configuration.

Development

The ActiveGate plugins how-to topics will guide you through the key concepts of ActiveGate plugin development with examples and working code snippets to facilitate your own plugin development.