Extension SDK commands

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