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 --helpusage: 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.jsonbuild_plugin builds pluginupload_plugin uploads plugin zipsimulate_plugin starts extension simulatorstart_demo_app starts demo applicationoptional 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_pluginChecking plugin metadata: c:\work\plugin_development\custom.remote.python.stress\plugin.jsonValidating plugin.json against schemaPlugin 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.confproperties.jsonsimulator_snapshot.json*.logfile_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_DIRplugin source directory-d DEPLOYMENT_DIR, --deployment_dir DEPLOYMENT_DIRdestination 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 SERVERserver address (taken from oneagent configuration fileby default)-t TOKEN, --token TOKENset the authentication token (token file is used iftoken is not set)-T TOKEN_FILE, --token_file TOKEN_FILEset the authentication token file (by default envvariable ONEAGENT_PLUGIN_UPLOAD_TOKEN, orplugin_upload.token from configuration directory,which is: C:\ProgramFiles\dynatrace\remotepluginmodule\agent\conf forremote plugin or: C:\Program Files(x86)\dynatrace\oneagent\agent\conf for localplugin,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_ZIPplugin zip path (default location ofoneagent_build_plugin is taken by default)-v, --verbose increase verbosity--no_cert_ver turn off ssl certificate verification-s SERVER, --server SERVERserver address (taken from oneagent configuration fileby default)-t TOKEN, --token TOKENset the authentication token (token file is used iftoken is not set)-T TOKEN_FILE, --token_file TOKEN_FILEset the authentication token file (by default envvariable ONEAGENT_PLUGIN_UPLOAD_TOKEN, orplugin_upload.token from configuration directory,which is:%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conffor remote plugin or:%PROGRAMDATA%\dynatrace\oneagent\agent\config forlocal 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.tokenAttempting to send plugin to server https://environmentid.dynatrace.com:443/api/v1/remotepluginsserver 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_plugin
command enables you to quickly test your code without deploying your extension and/or uploading it to Dynatrace server.
For more information, see extension simulator