Custom monitoring plugins now available (EAP)

With custom plugins you can extend Dynatrace with additional metrics that support your organization’s unique monitoring needs. Custom metrics are displayed in the Dynatrace UI alongside the standard set of performance metrics. Custom monitoring plugins are now available to participants of our Early Access Program.

Custom plugins can be created for any process that exposes an interface, such as metrics served over HTTP (for example, databases, applications, and load balancers). You can even define alerting criteria so that problems are raised whenever certain thresholds are breached.

Custom monitoring plugins are a great choice for:

  • Proprietary applications
  • Technologies that Dynatrace detects, but doesn’t yet provide tech-specific insights into.

Each custom plugin package is comprised of a Python script and a JSON file that includes all the metadata required to run the script (including libraries, if needed). OneAgent manages and executes plugins, so installation of OneAgent is required.

The Dynatrace plugin framework is equipped with advanced troubleshooting capabilities to help you pinpoint any issues in your plugin setup—from syntax to semantic and communication errors.

Get started with the demo plugin

To make it easy to get started with plugin creation, the Dynatrace SDK provides a demo plugin that monitors a simple Python-based demo web app. The plugin listens on localhost:8080 and responds to HTTP requests with a small JSON document that looks like this:

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

The Counter value increases with each hit on the page, while Random is a randomly-generated number.

Design… Develop… Deploy!

This post explains everything you need to know to get started building your first plugin. The high-level steps are illustrated below.


During the design phase you specify the metrics that you want to collect. For the demo Python app we’ll write a plugin that gathers two metrics: Counter and Random. If you want your plugin to raise alerts, you can define alerting criteria in the plugin.json file.

  1. Prepare the environment. Your DEV environment needs to be equipped with:
    • Python 3.5
    • OneAgent
    • OneAgent SDK
  2. The OneAgent SDK can be downloaded. Go to Settings > Monitored Technologies > Custom extensions. Click Download SDK.
    The OneAgent SDK is shipped as a zip archive, containing this documentation and a Wheel package. You may install the SDK Wheel package using pip, for example:
    pip install ruxit_sdk-
  3. Write the Python code and create the plugin.json file.
    The file defines one class, DemoPlugin, which in turn defines one method, - query. When your plugin runs, this method is called each minute to collect monitoring data and forward it to Dynatrace Server. This particular query method does the following:pgi = self.find_single_process_group(pgi_name('ruxit_sdk.demo_app'))
    pgi_id = pgi.group_instance_idAll Dynatrace metrics are associated with an entity ID. Briefly, process snapshots are data structures that contain a mapping between running processes and their IDs, as assigned by OneAgent. To send data, we need to search the snapshot. We use the find_single_process_group() method for this.stats_url = "http://localhost:8080"
    stats = json.loads(requests.get(stats_url).content.decode())Once we’ve acquired the ID, we need to gather the stats. This is easily achieved with the help of a requests package.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)Finally, once we have both the data to report and the entities that the data are associated with, we can handle things using the results_builder object. ResultsBuilder stores and processes the data that is sent to it (in other words, when you submit measurements as relative, ResultsBuilder automatically computes the difference from the previously reported measurement and only reports the difference).Now it’s time to take care of plugin.json.
    The plugin.json file begins with a few basic plugin properties: name, version, and type. The remaining properties (entity and processTypeNames) are used to inform OneAgent when it’s time to execute the plugin.

    "source": {
       "package": "demo_plugin",
       "className": "DemoPlugin",
       "install_requires": ["requests>=2.6.0"],
       "activation": "Singleton"

    The first two lines list the package name and className that are to be imported and executed by OneAgent. These properties correspond to the name of the Python file that contains the code and the name of the class defined in it.

    "metrics": [
    "timeseries": {
    "key": "random",
    "unit": "Count"
    "timeseries": {
    "key": "counter",
    "unit": "Count"
    ] }

    The metrics section describes the data that’s gathered by the plugin. This section mirrors both what the demo app serves and what the Python code collects.

  4. Build your plugin package. This step is easily accomplished with the help of the ruxit_build_plugin command, which is available in the OneAgent SDK. Execute the following command (directory with plugin files):ruxit_build_pluginYou should see output similar to this:Plugin deployed successfully into /opt/ruxit/plugin_development/custom.python.demo_plugin
    Plugin archive available at /opt/ruxit/plugin_development/custom.python.demo_plugin.zipThe plugin package is now available for upload to the server.
  5. Upload the plugin. Custom plugins can be uploaded to Dynatrace Server in one of two ways using either CLI or the Dynatrace UI (the choice is yours). Note that command line-based upload requires a token to authenticate the action. To generate the right token for you environment, go to Settings > Monitored technologies > Custom extensions. Execute the following command via CLI:ruxit_upload_plugin –t generated token
    You should see output similar to this:Starting net HTTPS connection:
    Plugin has been uploaded successfully.Or upload via the Dynatrace UI. Go to Settings > Monitored technologies > Custom extensions.
    Once uploaded, your plugin will appear in the custom plugins list.
  6. Restart OneAgent so that it can load and run the new plugin. Depending on your operating system, restart of OneAgent can be achieved in a few different ways.
    – On Ubuntu, type: sudo service ruxitagent restart
    – On Windows, go to Service Manager and restart the OneAgent service, or type:net stop "OneAgent" && net start "OneAgent"
  7. Check the metrics in the Dynatrace UI. Custom plugin metrics are displayed on Process metrics dashboards (accessible by clicking the Further details tab on related Process details pages).

It’s deployment time!

Once you decide that your plugin is ready for distribution, you need to promote it from the Staging state to the Production state. Go to Settings > Monitored technologies > Custom extensions. Select the plugin and click the Upgrade now button.

Now deploy the plugin by copying the files generated by the ruxit_build_plugin tool to the plugin_deployment folder in root of your OneAgent installation. Or use configuration management tools such as Puppet, Chef, or Ansible. Don’t forget to restart all instances of OneAgent once you’re done.

While this post gives you a great head start at plugin development, for more advanced scenarios and references, please refer to the OneAgent SDK.

If you’re interested in becoming a participant of our Early Access Program, please send us an email.