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 meter needs to be installed on the host where you are going to deploy a local plugin.

File System 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*).  

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:

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

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.

• Enter the new directory, and create a sub-directory with the name of the plugin.

• Enter the plugin directory, and clone the plugin into the target dir "plugin"

• Copy the plugin param.json to the current directory, and edit it if desired to set the plugin parameters.

• 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.

• If the meter is not running, start the meter.  You should see some messages appear.