Extension SDK commands

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.

The extension SDK contains a number of useful deployment and development tools provided in the form of the command-line Python scripts.

plugin_sdk

The plugin_sdk command is a single entry point to all the commands. It enables you to run a sequence of the SDK the 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 extension simulator
    start_demo_app      starts demo application

optional arguments:
  -h, --help            show this help message and exit
  --version             show program 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 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 extension 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 is used. The command creates the extension 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 extension 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_blocklist.txt

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

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

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

As the next step, oneagent_build_plugin attempts to upload the extension package to the Dynatrace server. You need to provide the server URL and a token to do this. Again, thhe server URL is automatically discovered if the plugin module is installed on the machine, otherwise provide server address by -s attribute.

Token string can be provided by token file, there is no need to specify it if it's located in the default directory. Otherwise the location of the file has to be specified by -T argument. It can also be provided as a string using -t argument or the script will request to enter it interactively, see plugin_build usage description below.

Pay attention to the upload result. If it fails, you'll learn the reason from the command output.

usage: plugin_build.py [-h] [-p PLUGIN_DIR] [-d DEPLOYMENT_DIR] [-v]
                       [--no_upload] [--no_cert_ver] [-s SERVER] [-t TOKEN]
                       [-T TOKEN_FILE] [--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
  -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:\Program
                        Files\dynatrace\remotepluginmodule\agent\conf for
                        remote plugin or: C:\Program Files
                        (x86)\dynatrace\oneagent\agent\conf for local
                        plugin,if env variable is not specified)
  --version             show program's version and exit

upload_plugin

The upload_plugin command uploads the extension 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:
                        %PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf
                        for remote plugin or:
                        %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://environmentid.dynatrace.com:443/api/v1/remoteplugins
server https://environmentid.dynatrace.com.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_plugincommand enables you to quickly test your code without deploying your extension and/or uploading it to Dynatrace server.

For more information, see extension simulator