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.

1(sdk) c:\work\plugin_development\custom.remote.python.stress>plugin_sdk --help
2usage: plugin_sdk [-h] [--version]
3                  {verify_plugin,build_plugin,upload_plugin,simulate_plugin,start_demo_app}
4                  ...
5
6Use one of the following arguments to invoke a certain command. See 'plugin_sdk
7<command> --help' to read about specific commands.
8
9positional arguments:
10  {verify_plugin,build_plugin,upload_plugin,simulate_plugin,start_demo_app}
11    verify_plugin       checks plugin.json
12    build_plugin        builds plugin
13    upload_plugin       uploads plugin zip
14    simulate_plugin     starts extension simulator
15    start_demo_app      starts demo application
16
17optional arguments:
18  -h, --help            show this help message and exit
19  --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.

1usage: plugin_sdk [-h] [-p PLUGIN_DIR] [-v] [--version]
2
3optional arguments:
4  -h, --help            show this help message and exit
5  -p PLUGIN_DIR, --plugin_dir PLUGIN_DIR
6  -v, --verbose         increase verbosity
7  --version             show program version and exit

Sample result:

1(sdk) c:\work\plugin_development\custom.remote.python.stress>plugin_sdk verify_plugin -p .
2Arguments: ['C:\\work\\virtualenv\\sdk\\sdk\\Scripts\\plugin_sdk', '-p', '.']
3Arguments=Namespace(plugin_dir='.', verbose=False)
4Starting oneagent_verify_plugin
5Checking plugin metadata: c:\work\plugin_development\custom.remote.python.stress\plugin.json
6Validating plugin.json against schema
7Plugin 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:

1token.conf
2properties.json
3simulator_snapshot.json
4*.log
5file_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.

1usage: plugin_build.py [-h] [-p PLUGIN_DIR] [-d DEPLOYMENT_DIR] [-v]
2                       [--no_upload] [--no_cert_ver] [-s SERVER] [-t TOKEN]
3                       [-T TOKEN_FILE] [--version]
4
5optional arguments:
6  -h, --help            show this help message and exit
7  -p PLUGIN_DIR, --plugin_dir PLUGIN_DIR
8                        plugin source directory
9  -d DEPLOYMENT_DIR, --deployment_dir DEPLOYMENT_DIR
10                        destination dir to deploy plugin
11  -v, --verbose         increase verbosity
12  --no_upload           turn off upload to the server
13  --no_cert_ver         turn off ssl certificate verification
14  -s SERVER, --server SERVER
15                        server address (taken from oneagent configuration file
16                        by default)
17  -t TOKEN, --token TOKEN
18                        set the authentication token (token file is used if
19                        token is not set)
20  -T TOKEN_FILE, --token_file TOKEN_FILE
21                        set the authentication token file (by default env
22                        variable ONEAGENT_PLUGIN_UPLOAD_TOKEN, or
23                        plugin_upload.token from configuration directory,
24                        which is: C:\Program
25                        Files\dynatrace\remotepluginmodule\agent\conf for
26                        remote plugin or: C:\Program Files
27                        (x86)\dynatrace\oneagent\agent\conf for local
28                        plugin,if env variable is not specified)
29  --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.

1usage: plugin_sdk [-h] [-p PLUGIN_ZIP] [-v] [--no_cert_ver] [-s SERVER]
2                  [-t TOKEN] [-T TOKEN_FILE]
3
4optional arguments:
5  -h, --help            show this help message and exit
6  -p PLUGIN_ZIP, --plugin_zip PLUGIN_ZIP
7                        plugin zip path (default location of
8                        oneagent_build_plugin is taken by default)
9  -v, --verbose         increase verbosity
10  --no_cert_ver         turn off ssl certificate verification
11  -s SERVER, --server SERVER
12                        server address (taken from oneagent configuration file
13                        by default)
14  -t TOKEN, --token TOKEN
15                        set the authentication token (token file is used if
16                        token is not set)
17  -T TOKEN_FILE, --token_file TOKEN_FILE
18                        set the authentication token file (by default env
19                        variable ONEAGENT_PLUGIN_UPLOAD_TOKEN, or
20                        plugin_upload.token from configuration directory,
21                        which is:
22                        %PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf
23                        for remote plugin or:
24                        %PROGRAMDATA%\dynatrace\oneagent\agent\config for
25                        local plugin, if env variable is not specified)

Example usage. Note the VALIDATION_ERROR_VERSION_CONFLICT error.

1(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"
2Arguments: ['C:\\work\\virtualenv\\sdk\\sdk\\Scripts\\plugin_sdk', '-p', 'c:\\Program Files\\dynatrace\\remotepluginmodule\\plugin_deployment\\custom.remote.python.stress.zip']
3reading token from file C:\Program Files\dynatrace\remotepluginmodule\agent\conf\plugin_upload.token
4Attempting to send plugin to server https://environmentid.dynatrace.com:443/api/v1/remoteplugins
5server https://environmentid.dynatrace.com.com:443/api/v1/remoteplugins/ returned status code: 400 {"error":{"code":400,"message":"VALIDATION_ERROR_VERSION_CONFLICT"}}
6Please 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