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

  1. Check prerequisites:
    • Dynatrace version 1.189+
    • OneAgent v1.189+
    • Monitoring admin access
  2. Install Python 3.8. OneAgent is bundled with Python 3.8. We recommend that you use Extension SDK with the same Python version.

To run extensions with OneAgent installed on Amazon Linux 2022, you need to install the libxcrypt-compat library.

Download OneAgent Extensions SDK

  1. Go to Settings > Monitoring > Monitored technologies > Add new technology monitoring > Add OneAgent extension.
  2. On the Build OneAgent extension with Python page, select Download Extensions SDK.
    This downloads a ZIP archive of the SDK.
  3. Extract the ZIP file to a convenient directory.
    • The archive contains docs, examples, and the Extensions SDK whl file that you'll use to install the SDK.
    • You'll find example extensions in the examples directory. In this tutorial, we'll use the extension located in the demo_oneagent_plugin directory.

Install OneAgent Extensions SDK

Python Virtual Environment

We recommend that you install the Extensions SDK using Python Virtual Environment. For guidance, see Virtual Environments and Packages in Python documentation.

  1. Navigate to the extracted directory with the whl file in it and run the following command:
    pip3 install plugin_sdk-[sdk version number]-py3-none-any.whl
    for example
    pip3 install plugin_sdk-1.189.0.20200213.160436-py3-none-any.whl
  2. Run plugin_sdk --help to verify the Extensions SDK installation. For more information, see Install Extensions SDK.

Deploy the extension

Things to remember

  1. You must upload the extension to both the Dynatrace Cluster and to the OneAgent-monitored host where the extension will be executed.
    • If you've already installed the Extensions SDK on the OneAgent-monitored host, the build_plugin command will take care of OneAgent for you.
    • If you've installed the Extensions SDK on a different host, which is a more common scenario, upload your extension to the OneAgent-monitored host manually and save in the /opt/dynatrace/oneagent/plugin_deployment directory. During the development stage, we recommend that you install Extensions SDK on the OneAgent-monitored host to make your development process easier.
  2. You can't deploy the same extension version twice. To upload a modified extension, make sure that you increment the extension version with each build or upload. Use the version property in the metadata section of your JSON definition.

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

  1. Go to Settings > Monitoring > Monitored technologies.

  2. Select Add new technology monitoring.

  3. In the Monitor any technology section, select Add OneAgent extension.

  4. You'll see a high-level overview of the steps required to develop your extension, along with the Upload extension button.

    Extension demo download sdk

  5. Upload the custom.python.demo_plugin.zip package you've just built.

  6. After successful upload, you should find the extension on the Monitored technologies page in the Dynatrace web UI, on the Custom extensions tab.

    Extension demo upload

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.

  1. Start the demo application. Navigate to the directory where you extracted the SDK and run the following command:

    plugin_sdk start_demo_app

  2. Verify that your application is up and running. Go to http://127.0.0.1:8769/ and check that the application is responding.

    When run without parameters, the application listens on localhost:8769 and responds to HTTP requests with the following JSON:

    {
    "version": "1.001",
    "random": 907,
    "counter": 116,
    "state": "ERROR",
    "stat_counter": [
    6,
    10,
    12,
    ],
    "battery_level": 88.4
    }

    The counter value increases with each hit to the page, while random is a random number generated with each hit.

    You can list the parameters of the demo application using:

    plugin_sdk start_demo_app --help

    These include the parameters for changing the default port and enabling authentication.

  3. Wait patiently. It can take up to 2 minutes for the first data to be collected.

Look around

  1. Navigate to the Host overview and select the plugin_sdk.demo_app process.

    Extension demo host

  2. The Process overview page appears. Select Further details.

    Extension demo pgi

  3. The Process metrics page is displayed.

    Extension demo metrics

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:

The metadata contains a list of properties that are used to identify your extension.

{
"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"]
}
}

The extension name should follow ^custom.python(\.[a-zA-Z0-9_]+)+$ regex. For example, custom.python.my_plugin_2. The name of each extension must be unique.

The technologies and favicon properties determine how your technology is presented on the Technology overview page in the Dynatrace web UI. To have data from your extension displayed on an existing technology tile, specify a matching technology name. You can look up supported technology names in the JSON file or you can find them in the UI as the Main technology process property.

To make an extension independent from a process, do not define the technologies property.

The package name and class that is to be imported and executed by OneAgent correspond to the name of the Python file that contains the code and the name of the class that’s defined in it.

The metrics section describes the data gathered by the extension. This section provides two metrics that mirror both what our demo application serves, and what the Python code collects.

ConfigUI and the properties sections define the user interface elements used for extension configuration.

This part of the JSON file defines how metrics are charted. The key metrics section allows you to select the most important metrics and present them in the infographic and on the metric group page. You'll find charts on the Further details tab.

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.