Follow

Installing Local Plugins

Local plugins refer to the deployment of a meter plugin in the host's local file system. Deploying a plugin in this manner bypasses the conventional means via the Web Interface. Installation within the file system can be performed using any means at your disposal. This opens the possibility for scaling out deployments of meters on hosts using native packaging systems (apt, rpm, msi, etc) for their respective platforms.

Prerequisites

The TrueSight Pulse meter needs to be installed on the host where you are going to deploy a local plugin.

NOTE: From meter version 4.5.1 or later please see the following knowledge article.

FileSystem Organization/Structure

The table below assumes the /etc/truesight/ directory location for TrueSight meter configuration, but it can vary by platform/OS.  All of these files and directories should be owned by the "truesight" user and "truesight" group (e.g. chown -R truesight:truesight local_plugins*).  

Directory or File Description
/etc/truesight/local_plugins.conf A JSON config file specifying which local plugins are present and which are enabled or disabled (see below for the format)
/etc/truesight/local_plugins/ The directory containing all the local plugin configurations and the plugin code (or symbolic links to the plugin code)
/etc/truesight/local_plugins/plugin_A/ This directory is named for the plugin as it appears in the local_plugins.conf file
/etc/truesight/local_plugins/plugin_A/param.json The standard config file for this plugin
/etc/truesight/local_plugins/plugin_A/plugin/ This can be a standard directory or a symbolic link to another directory where the plugin code is stored (e.g. ln -s /var/lib/boundary/plugins/plugin_A plugin)
/etc/truesight/local_plugins/plugin_B/ This directory is named for the plugin as it appears in the local_plugins.conf file
/etc/truesight/local_plugins/plugin_B/param.json The standard config file for this plugin
/etc/truesight/local_plugins/plugin_B/plugin/ This can be a standard directory or a symbolic link to another directory where the plugin code is stored (e.g. ln -s /var/lib/boundary/plugins/plugin_B plugin)

For Windows systems, the above applies with the following exceptions:

  • the local_plugins.conf file and local_plugins directory appear in the same install directory as the meter (e.g. C:\Program Files\TrueSight)
  • the code/files for each plugin must reside in the local_plugins/<plugin name>/plugin directories, they cannot be linked to other locations in the filesystem

The meter will periodically check the local_plugins.conf file for changes.  When changes are detected, the meter will reload the local_plugins.conf and do the following:

  • start any local plugins whose entries went from "disabled" to "enabled"
  • start any local plugins where were not previously listed in the local_plugins.conf file but are now listed as "enabled"
  • stop any local plugins whose entries went from "enabled" to "disabled"
  • stop any local plugins whose entries disappeared from the local_plugins.conf file

If a customer has a local plugin installed and tries to install the same plugin via the Premium UI, the meter will always prefer the local plugin to the one coming via the Premium UI and backend (the general rule of thumb is "local always wins").

local_plugins.conf

The format of the local_plugins.conf file is currently the following:

{
   "plugins": {
      "plugin-name": "<enabled | disabled>"
   }
}

So for our example above, a local_plugins.conf file where both plugins are enabled would look like this:

{
   "plugins": {
      "plugin_A": "enabled",
      "plugin_B": "enabled"
   }
}

Example #1

Here is how to configure the ping check plugin as a local plugin so you can configure multiple checks by just editing a configuration file:

  1. Deploy the ping check plugin on a single host using the web UI (so you have a working template). 
  2. Stop the Meter service: service truesight-meter stop. 
  3. Create /etc/truesight/local_plugins. 
  4. Create a sub-directory to store the plugin contents with the same name as the plugin: /etc/truesight/local_plugins/pingcheck. 
  5. Copy the contents of /etc/truesight/plugins/pingcheck (installed previously) to /etc/truesight/local_plugins/pingcheck/plugin. 
  6. Move the file /etc/truesight/local_plugins/pingcheck/plugin/param.json to /etc/truesight/local_plugins/pingcheck/param.json. 
  7. Add the local_plugins.conf (example attached) to /etc/truesight. 
  8. Remove the plugin from the meter using the Web UI (to get rid of the UI-installed copy) 
  9. Restart the Meter service: service truesight-meter start

To add subsequent ping check configurations perform the following:

  1. Stop the Meter service: service truesight-meter stop 
  2. Edit the /etc/truesight/local_plugins/pingcheck/param.json (it should be apparent what needs to be added to the JSON format configuration file). 
  3. Start the Meter service: service truesight-meter start

This is just an example of course.

 

Example #2

In this example, we will install the cpu_core plugin locally

  • Change directory to your meter configuration location.  Typically /etc/truesight, and make a "local_plugins" directory if one is not present.
       cd /etc/truesight
       mkdir local_plugins
  • Enter the new directory, and create a sub-directory with the name of the plugin.
       cd local_plugins
       mkdir truesight-plugin-cpu-core
  • Enter the plugin directory, and clone the plugin into the target dir "plugin"
       cd boundary-plugin-cpu-core
       git clone https://github.com/boundary/boundary-plugin-cpu-core.git plugin
  • Copy the plugin param.json to the current directory, and edit it if desired to set the plugin parameters.
       cp plugin/param.json .
       vi param.json if you wish.
  • Note: Some plugins require additional setup via a Post Install command.   This command, if required, can be found in the plugin/plugin.json file.
    • For lua plugins, the command is in the "postExtract_lua" section, for others, it's in the "postExtract" section
    • Eg:  "postExtract" : "npm install"
    • If this field is present, do the following:

      cd plugin
      npm install # Execute the appropriate post extract command.  

       

  • Return to the meter configuration directory and create/edit the local_plugins.conf file to add/enable the new plugin.
       cd /etc/truesight
       vi local_plugins.conf
                    {
                         "plugins": {
                             "trueight-plugin-cpu-core": "enabled"
                         }
                   }
  • If the meter is not running, start the meter.  You should see some messages appear.
       [v4.4.1-1: pluginmg: 0097,stderr_cb] [v4.4.1-1: pluginmg: 1625,local_plugins_ch] conf/local_plugins.conf found, processing...
       [v4.4.1-1: pluginmg: 0097,stderr_cb] [v4.4.1-1: pluginmg: 1397,start_local_plug] starting local plugin 'TrueSight CPU Core Plugin' (version 0.9.3, installed as truesight-plugin-cpu-core)...
Have more questions? Submit a request