TrueSight API Documentation
OverviewAccountActionsAdministration
Alarms v1Alarms v2BatchingDashboards
DatasetsEventsExtended Metrics
GroupsHostgroupsMetersMetricsProduct
PluginsRelaysSourcesSource-TagsSynchronize Data
Tenants
Terms

Plugins

A TrueSight Pulse Plugin is a small application written in any language that regularly reports arbitrary metrics that may optionally include one or more dashboards. Plugins are open source and are submitted via a pull request to the TrueSight Pulse github plugin repository. Once a plugin is accepted into the repository it appears in the Plugins tab of the Settings dialog. After a plugin is installed into your account you will need to go to Relays tab in order to install plugin instances on corresponding host(s).

See this tutorial on how to write your own plugin.

Anatomy of a plugin

A plugin consists of a github repository. All plugins are open source so the repository should be made public (note: github supports public repositories free of charge). The plugin repository is required to have at least one file, plugin.json. This and other files are described below:

plugin.json

A JSON description of the plugin, see below.

readme.md (optional)

A markdown formatted description of the plugin. This will be displayed within the TrueSight Pulse settings dialog when browsing available plugins.

icon.png (optional)

An icon to display next to the plugin when browsing plugins in the TrueSight Pulse settings dialog. Should be a 48x48 pixel PNG.

plugin files + directories (optional)

Any other files required to run the plugin. All files in the repository are installed with the plugin.

Plugin.json

The plugin.json file describes the plugin and also provides metadata displayed to users when browsing available plugins. Below is a sample plugin.json:

{
    "description" : "Scans the given device mount paths and reports the one with the least free space",
    "icon" : "icon.png",
    "command" : "node index.js $(pollInterval) $(devices)",
    "postExtract" : "npm install",
    "ignore" : "node_modules",
    "metrics" : ["DISKUSE_SUMMARY"],
    "paramSchema" : [
        {
            "title" : "Devices",
            "description" : "The set of device mountings to check for free space.",
            "type" : "array",
            "items" : {
                "type" : "string"
            }
        }
    ]
}

The following properties can be specified:

command

A shell command that does the polling for metric data. The plugin will typically contain other programs or scripts which do the work of polling for metrics. The process is launched with this command. There are two possible ways to perform polling:

The command can also contain macros. A macro is enclosed by $() as follows:

$(someMacro)

All parameters specified by the paramSchema (below) can be used as macros as well as builtin values. At present there is one builtin value:

If you choose to not pass parameters using macros in the command you can open a file named param.json which will be created in the root directory of your plugin prior to launch. All known parameters will appear in this file.

metrics

An array of TrueSight Pulse metric identifiers. This is the set of metrics that the plugin will be providing. Use the Metrics tab in the Settings dialog to create new metrics. When the plugin is installed, TrueSight Pulse will check that these metrics exist in the account. If the metrics do not exist in the account (for example, if another user outside of the account used to create the plugin installs the plugin for the first time) then an instance of the metrics are copied into the account.

dashboards (optional)

An array of dashboards to add on install of the plugin. Each item in the array is an object with two properties; name and layout. The name will be displayed in the dashboard dropdown, the layout is a standard dashboard layout string available by clicking the 'Copy to clipboard' (copy to clipboard) icon from within the dashboard editor dialog.

description (optional)

A short description of the plugin to be displayed when browsing available plugins.

icon (optional)

An image in PNG format to be displayed next to the plugin listing when browsing available plugins. This image should be 48x48 pixels. If it is larger it will be resized.

postExtract (optional)

A command to execute after the plugin has been extracted. This is typically a build or install of dependencies.

ignore (optional)

The set of files/directories within the plugin to ignore when validating. In order to insure the correct version of a plugin is running, the TrueSight Pulse relay will compare checksums of all plugin files installed to the ones in the repository. If the plugin generates extra files when installing or executing it should list them here otherwise the TrueSight Pulse relay will attempt to re-install the plugin. Can be a string or an array of strings.

paramSchema (optional)

An array of parameter description blocks that describe configuration parameters for the plugin. Plugin parameters are described using a subset of the JSON schema specification. If specified, TrueSight Pulse will allow plugins to be remotely configured using the Settings dialog, Relays tab. After parameters are changed TrueSight Pulse will send the new settings out to the TrueSight Pulse relay which then passes them onto the plugin. A filed called param.json will be written into the plugin directory and the plugin will be restarted. Each parameter description block is an object that can contain the following properties:

ignoreErrors (optional)

A boolean that, if specified, tells the TrueSight Pulse relay to ignore any non-zero return codes from the plugin. By default a plugin is allow to fail 5 times, after which TrueSight Pulse relay will attempt to re-install the plugin. If the plugin then continues to fail the plugin will be disabled.

Reporting metric readings

A plugin reports metrics simply by writing to STDOUT. The TrueSight Pulse relay will capture the output, parse it, and pass it back to TrueSight Pulse for display. The output must be in the following format:

[<metric name>] <measure> [<source>] [<unix timestamp>]

Where:

For example, your plugin could output the following:

SOME_METRIC .5 serverX 1381857948

This output will create a graph point on the SOME_METRIC graph, at the value of .5, for the Unix Epoch time of 1381857948, and be part of the data series labelled serverX in the legend. Because of default values, the relay can assume most of the measurement values such that the follow are also valid output:

SOME_METRIC .5

Assumes the hostname of the relay for source and the current time for timestamp.

.5 serverX

Assumes the first metric listed in the metrics property for the plugin and the current time for timestamp.

.5

Assumes the first metric listed in the metrics property, the hostname of the relay for source, and the current time for timestamp.

Testing

In order to aid in testing deployment of plugins TrueSight Pulse provides an API to submit interim plugin revisions available within an account. Firstly, make sure the latest version of your plugin is checked into github. Now you can make an API call to add this version of your plugin to your account -

$ curl https://api.truesight.bmc.com/v1/plugins/private/myplugin/myusername/mypluginrepo \
-X PUT \
-u <email>:<api-token>

The plugin will now appear in the list of available plugins which appears after clicking Get Plugins from the Plugins tab in Settings. You will know it is your test plugin because the name will be followed by "(test)". You can now add to this one of your relays.

Just repeat the above to update the plugin as needed. After executing the above you can view the list of installed plugins for a relay and you should notice a link on the plugin labelled 'Apply Update'. After applying the update you should be able to see the latest version deployed, re-installed, and re-stared in the relay in the console.

Note: You should remove the test plugin once it has been accepted into the public repository (see Submission below). If you do not remove the test plugin, it will continue to "mask" whatever version is put in the public repository for your account. In other words, when browsing plugins in your account, the public list of plugins is first retrieved then overlaid with those test plugins with the same name. To remove a test plugin:

$ curl https://api.truesight.bmc.com/v1/plugins/private/myplugin \
-X DELETE \
-u <email>:<api-token>

Submission

Once a plugin is submitted it is available for any TrueSight Pulse user to install. To submit a plugin you should do the following (note: it is assumed that you have installed git and have enabled SSH by adding your rsa key):

1) Create a github account if you don't already have one

2) Visit the graphdat/contrib repository and click the Fork button

fork graphdat contrib

3) Clone the repository to your local directory

$ git clone git@github.com:mygithubname/contrib.git

4) Create a submodule in the /plugins folder using your plugin repository

$ cd contrib
$ git submodule add git@github.com:mygithubname/myplugin-graphdat.git plugins/myplugin

5) Push your submodule changes to your forked repository

$ git add .
$ git commit -m "Add myplugin"
$ git push

6) Now use github to create a pull request. From the page of your fork, click on the Compare & Review button:

compare

..then click on 'Create a pull request for this comparison':

create

..and finally, 'Send pull request'

send

This will send a request to the TrueSight Pulse team to review and add your plugin to the public repository. You can update your submission by simply repeating from step #5 above. Once added your plugin will be visible from the 'Get plugins' button in the Plugins tab of the Settings dialog for all users.