Configuration¶

In this section you will learn how to provide a plugin with configuration from Dynatrace Cluster Node. To achieve this we will extend the plugin described in the first tutorial.

This new plugin will monitor an application that is similar to the one used earlier, except this time, reaching the statistics page requires that you provide credentials (via HTTP basic auth mechanism). The application is also included in the SDK. You can start it with:

python -m oneagent_sdk.demo_app_auth

By default this app listens on port 8090 and serves stats to the user authenticated with the ruxit:ruxit credentials. You can explore the options with python -m oneagent_sdk.demo_app_auth --help

Let's start by looking at the whole plugin.json and source of the plugin. Then we'll go over the modifications. Here's the plugin source code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

import requests
import requests.exceptions
import json
from ruxit.api.base_plugin import BasePlugin
from ruxit.api.snapshot import pgi_name


class DemoPlugin(BasePlugin):
    def query(self, **kwargs):
        config = kwargs["config"]
        user = config["user"]
        password = config["password"]
        pgi = self.find_single_process_group(pgi_name('oneagent_sdk.demo_app_auth'))
        pgi_id = pgi.group_instance_id
        stats_url = "http://localhost:8090"

        response = requests.get(stats_url, auth=(user, password))
        stats = json.loads(response.content.decode())
        
        self.results_builder.absolute(key='random', value=stats['random'], entity_id=pgi_id)
        self.results_builder.relative(key='counter', value=stats['counter'], entity_id=pgi_id)

And here's the corresponding plugin.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
  "version": "1.2",
  "name": "custom.python.demo_plugin_conf",
  "type": "python",
  "entity": "PROCESS_GROUP_INSTANCE",
  "processTypeNames": ["PYTHON"],
  "source": {
    "package": "demo_plugin_auth",
    "className": "DemoPlugin",
    "install_requires": ["requests>=2.6.0"],
    "activation": "Singleton"
  },
  "metrics": [
    {
      "timeseries": {
        "key": "random",
        "unit": "Count",
        "dimensions": []
      }
    },
    {
      "timeseries": {
        "key": "counter",
        "unit": "Count",
        "dimensions": []
      }
    }
  ],
  "configUI": {
    "displayName": "custom.python.demo_plugin_conf"
  },
  "properties": [
    {
      "key": "user",
      "type": "String"
    },
    {
      "key": "password",
      "type": "Password"
    }
  ]
}

Adding configuration for a plugin requires declaring the possible parameters in the plugin.json, like this:

    {
      "key": "user",
      "type": "String"
    },
    {
      "key": "password",
      "type": "Password"
    }
  ]

Each property needs to have a key and type specified. Additionally, you can specify a default value under the defaultValue key in JSON. In order to have the option of providing the configuration in web UI, you also need to specify the name you want your plugin to appear under on the web page. This is also done in plugin.json. It looks like this:

    "displayName": "custom.python.demo_plugin_conf"
  },
  "properties": [

Note that displayName and plugin.name don't have to be the same.

Please refer to plugin.json reference for further information regarding properties and configUI elements, including more descriptive field names, ordering of fields, and more.

Once you upload your plugin to Dynatrace Cluster Node, you can enter the desired configuration. Within web UI go to Settings > Monitored technologies > Custom plugins and select the custom.python.demo_plugin_auth plugin.

Expand the plugin configuration form, enter the credentials, and click Save:

If you've entered the credentials correctly, you should see that the plugin is doing fine:

Knowing how to declare required properties and entering them is not enough. You must also handle them in code. This is quite simple, and is accomplished like this:

        config = kwargs["config"]
        user = config["user"]
        password = config["password"]
        pgi = self.find_single_process_group(pgi_name('oneagent_sdk.demo_app_auth'))

And a few lines later:

        response = requests.get(stats_url, auth=(user, password))

Once OneAgent receives plugin configuration info from the server, it passes it to the query method under the config keyword in the form of a Python dictionary with keys that correspond to those present in the JSON file. Extracting configuration info from the dictionary and passing to the request library is straightforward.

Note: Your plugin will not be run until the configuration is entered on the server side. Meaning, the DemoPlugin object will not be created and the query method will not be called.

As a result, you don't need to worry about properties that aren't present in the dictionary. However, the provided values may still be invalid. To learn both how OneAgent handles this scenario and how to create effective error handling, please take a look at our error handling guide.