OneAgent extensions tutorial

Let’s learn by example. In this tutorial, we’ll walk you through the creation of a basic OneAgent extension. Your extension will enable monitoring of the demo application that's bundled with the extension SDK.

Prepare your environment

Download OneAgent Extensions SDK

Install OneAgent Extensions SDK

Deploy the extension

Things to remember

Build your extension

Navigate to the Extensions SDK \examples\demo_oneagent_plugin directory and run the plugin_sdk build_plugin --no_upload command. This will build the extension package from the current directory and copy the extension to the plugin_deployment folder OneAgent directory.

Starting build_plugin
Validating plugin.json against schema
Plugin data: Plugin name=custom.python.demo_plugin, version=1.0
...
========================================
Plugin deployed successfully into /opt/dynatrace/oneagent/plugin_deployment/custom.python.demo_plugin
Plugin archive available at /opt/dynatrace/oneagent/plugin_deployment/custom.python.demo_plugin.zip
========================================

Running the command requires write privileges for the target directory, usually /opt/dynatrace/oneagent on Linux and %PROGRAMFILES%\dynatrace\oneagent on Windows.

See build_plugin for more information.

Upload your extension

Congratulations, you've successfully deployed your first OneAgent extension.

Note that you can automate the upload to the Dynatrace Cluster using the Extensions SDK or the Dynatrace API.

Start the demo application

Your first OneAgent extension will monitor the demo application that's bundled with the Extensions SDK.

Look around

Customize the extension

The OneAgent extension consists of two key files, one Python file and one JSON file. The JSON file defines the presentation of your data on various Dynatrace pages. With the Python file, you can define additional events and create custom properties. Play around with the files to see how the data presentation is affected.

JSON file

The extension JSON file consists of the following four main elements:

{
  "name": "custom.remote.python.example_multi",
  "version": "1.18",
  "productiveMinVersion": "1.000",
  "requiredAgentVersion": "1.000",
  "type": "python",
  "entity": "CUSTOM_DEVICE",
  "metricGroup": "tech.Example_Service",
  "technologies": ["EXAMPLE_SERVICE"],
  "source": {
    "package": "demo_activegate_plugin_multi",
    "className": "RemoteExamplePlugin",
    "install_requires": ["requests>=2.6.0"]
  }
}

Python

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

import requests

from ruxit.api.base_plugin import BasePlugin
from ruxit.api.data import MEAttribute
from ruxit.api.snapshot import pgi_name


class DemoPlugin(BasePlugin):
    def query(self, **kwargs):
        pgi = self.find_single_process_group(pgi_name('plugin_sdk.demo_app'))
        pgi_id = pgi.group_instance_id
        stats_url = "http://localhost:8769"
        stats = requests.get(stats_url).json()
        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)
        self.results_builder.state_metric(key="state", value=stats['state'], dimensions={'app': 'demo'}, entity_id=pgi_id)
        self.results_builder.report_property(key="version", value=stats['version'],
                                             me_attribute=MEAttribute.CUSTOM_PG_METADATA, entity_id=pgi_id)

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

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

{"counter": 147, "random": 907}

The query method gathers some data from the demo application. The query method uses the HTTP request to receive the JSON response:

stats_url = "http://localhost:8769"
stats = requests.get(stats_url).json()

Now it's time to report the stats to the Dynatrace Cluster. To do that, define the entity that measurements are associated with. The entity consists of: ID, type, name, and process snapshot, which is a data structure that contains all information about processes related to the entity discovered by OneAgent. To get the list of all entities related to the extension defined by the activation context, use the following method:

entities = self.get_monitored_entities()

This method returns the list of entities that represent all the currently running Python processes.

You can report the data on three levels: the monitored host EntityType.HOST, the monitored process EntityType.PROCESS_GROUP_INSTANCE, or the process group EntityType.PROCESS_GROUP. Pass the EntityType argument to the get_monitored_entities method. If no argument is given, the entity property of plugin.json will be taken.

Next steps

This is just the beginning. Check out other example extensions that are delivered with the SDK and get to know which (technologies are supported using extensions forum.