Write your first ActiveGate plugin

Beta

Let’s learn by example. In this tutorial, we’ll walk you through the creation of a basic ActiveGate plugin. Your ActiveGate plugin will execute on an ActiveGate and monitor the demo application bundled with the Plugin SDK.

What you will need:

  • Dynatrace v1.156 or newer with Environment ActiveGate v1.155 or newer.
  • Dynatrace monitoring admin access.
  • ActiveGate plugin module installed on the Environment ActiveGate you'll use to run the plugin. See Installing ActiveGate plugin module
  • Python 3.6 with pip installed on your development machine. See Installing Python.

Install Plugin SDK

  1. Sign in to Dynatrace and navigate to Settings > Monitored technologies > Add new technology monitoring > Add ActiveGate plugin. Click Download Plugin SDK. ActiveGate Plugins Download SDK
  2. Extract the archive to a convenient directory. It contains docs, examples and the Plugin SDK whl file you'll use to install the SDK (e.g. plugin_sdk-1.156.0.20181003.61122-py3-none-any.whl).
  3. Install Plugin SDK. Navigate to the extracted directory with the whl file in it and run the following command: pip3 install plugin_sdk-1.156.0.20181003.61122-py3-none-any.whl

Get the demo plugin ready

Your first ActiveGate plugin will monitor the demo app bundled with the SDK. The demo app simulates the CUSTOM TECHNOLOGY that runs on a cluster with two nodes. The demo app API provides access to two metrics per each node. Your plugin will import the topology and fetch the metrics. This is an expected result. ActiveGate Plugins Tech Overview

  1. Start your the demo app. Navigate to the directory where you extracted the SDK and run the following command: python -m plugin_sdk.demo_app
  2. Copy the ActiveGate demo plugin.
  • Copy the demo demo_activegate_plugin directory to plugin_deployment directory on your ActiveGate. By default, it's C:\Program Files\dynatrace\remotepluginmodule\plugin_deployment on Windows or /opt/dynatrace/remotepluginmodule/plugin_deployment on Linux.
  • Restart the Dynatrace Remote Plugin Module service to make ActiveGate import the new plugin.
  1. Upload the plugin to Dynatrace. Go to Settings > Monitored technologies, select the Custom plugins tab and click Upload ActiveGate plugin button. Upload either the plugin.json file or the whole zip acrhive containing the plugin files prepared earlier. ActiveGate Plugins Upload
  2. Verify the successful plugin upload in the Custom plugins tab. See Deploy custom plugin for more information. ActiveGate Plugins Configure

Start the demo plugin

  1. Stay in the Custom plugins tab. Click the newly uploaded plugin to access the configuration page. Define the endpoint name and set the URL to http://localhost:8769. Select the ActiveGate on which you installed the plugin. Click Add endpoint. ActiveGate Plugins Activate

  2. Verify the successful plugin start.

  • The Demo Plugin should display the Ok status. ActiveGate Plugins Verify
  • Click the Monitored processes button to access the Technology overview page. It will indicate the plugin has connected to CUSTOM TECHNOLOGY, and a group with two instances (nodes) has been created. Note the custom technology icon. ActiveGate Plugins Tech Overview

Look around

The Group page lets you analyze the group and compare the performance of its members. ActiveGate Plugins Group

You'll find the node metrics in the infographic and Further details tab. ActiveGate Plugins Further Details

Customize the plugin

The ActiveGate plugin consist of the two key files, Python and JSON. The JSON file defines the presentation of your data on various screens. With the Python file, you can define additional events and create custom properties. See ActiveGate plugins reference and the ActiveGate plugins capabilities. Try to play with the files and see how it affects the data presentation.

JSON

The plugin JSON file consists of the 4 main elements:

Python

The Python code is stored in the demo_activegate_plugin.py file.

Demo Python code
Download
import json
import requests
from ruxit.api.base_plugin import RemoteBasePlugin
import logging

logger = logging.getLogger(__name__)

class DemoPluginRemote(RemoteBasePlugin):
    def initialize(self, **kwargs):
        config = kwargs['config']
        logger.info("Config: %s", config)
        self.url = config["url"]

    def query(self, **kwargs):
        #Create topology
        url = self.url + "/topology"
        topology = json.loads(requests.get(url).content.decode())
        for group_t in topology:
            group_name = group_t['name']
            group = self.topology_builder.create_group(group_name, group_name)
            for node_t in group_t['nodes']:
                node_name = node_t['name']
                node = group.create_element(node_name, node_name)
                logger.info("Topology: group name=%s, node name=%s", group.name, node.name)
                #Collect stats
                stats = node_t['stats']
                node.absolute(key='countercd', value=stats['counter'])
                node.relative(key='randomcd', value=stats['random'])

The file defines the DemoPluginRemote class, which in turn defines one method query. When your plugin runs, this method is called once each minute to collect and send topology data and metrics to Dynatrace Server.

The demo app returns the JSON response as in the example below.

ActiveGate Plugins JSON response

Plugin’s query method parses the response, finds groups, nodes and assigns metrics accordingly. The plugin automatically detects and monitors new groups and nodes.

Next steps

This is basic example of what you can achieve with ActvieGate plugins. To learn more, see ActiveGate plugins capabilities, read ActiveGate plugins reference or explore topics.