With custom plugins you can extend Ruxit with additional metrics that support your organization’s unique monitoring needs. Custom metrics are displayed in the Ruxit 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 Ruxit 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). Ruxit Agent manages and executes plugins, so installation of Ruxit Agent is required.

The Ruxit 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 Ruxit 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.

plugin_development_process

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
    • Ruxit Agent
    • Ruxit SDK
  2. The Ruxit SDK can be downloaded from Ruxit. Go to Settings > Monitored Technologies > Custom extensions. Click Download SDK.
    Ruxit_SDK
    The Ruxit 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-1.98.0.20160601.192338-py3-none-any.whl
  3. Write the Python code and create the plugin.json file.
    sample_plugin
    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 Ruxit 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 Ruxit 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 Ruxit Agent. 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.

    JSONfile
    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 Ruxit Agent 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 Ruxit Agent. 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 Ruxit 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.zip

    The plugin package is now available for upload to the server.

  5. Upload the plugin. Custom plugins can be uploaded to Ruxit Server in one of two ways using either CLI or the Ruxit 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: tenantname.live.ruxit.com.
    Plugin has been uploaded successfully.Or upload via the Ruxit UI. Go to Settings > Monitored technologies > Custom extensions.
    plugin_upload
    Once uploaded, your plugin will appear in the custom plugins list.
  6. Restart Ruxit Agent so that it can load and run the new plugin. Depending on your operating system, restart of Ruxit Agent can be achieved in a few different ways.
    – On Ubuntu, type: sudo service ruxitagent restart
    – On Windows, go to Service Manager and restart the Ruxit Agent service, or type:net stop "Ruxit Agent" && net start "Ruxit Agent"
  7. Check the metrics in the Ruxit UI. Custom plugin metrics are displayed on Process metrics dashboards (accessible by clicking the Further details tab on related Process details pages). 
    plugin_metrics

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.

plugin_upgrade

Now deploy the plugin by copying the files generated by the ruxit_build_plugin tool to the plugin_deployment folder in root of your Ruxit Agent installation. Or use configuration management tools such as Puppet, Chef, or Ansible. Don’t forget to restart all instances of Ruxit Agent 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 Ruxit SDK.

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