Page History
...
From the example here, you can see that windows allows you access environment variables by wrapping the name in % characters, i.e. %UPTIME_HOSTNAME%. So we've used that to arrange the input variables from xml into the order expected by the rcs.php script. You may also notice the ..\..\..\apache\php\php.exe path used to start php. Whenever a script monitor is triggered the current working directory is set to the location of the script itself, which is in this case is C:\Program Files\uptime software\uptime\plugins\scripts\monitor-custom-remote\monitor-custom-remote.bat. But the location of the UIM directory can vary depending on where it was initially installed. So we use a relative path from the plugin's location to find <uptime_dir>\apache\php\php.exe. When making your own plugins, you can usually simplify this by using the hard-coded path of your UIM directory.
...
We won't get into the details of the rcs.php script itself as this will typically change changes depending on the details of the plugin itself. But the full contents of this file on GitHub here if you are interested.
...
You may wonder where the 'custom1' string is coming from as it's not in the example output of the agent side script above. This is inserted by the rcs.php and used to mark that the output from the agent script should link up with the 'custom1' variable from the XML. Which you can see on the next line Output where 'custom1' is replaced with that variable's short description also from the xml. The next line is an example of UIM attempting parse the second line of output from our agent script into a variable called 'MON' but because this isn't defined in our xml file, it won't be available for comparisons within the GUI. The final line here is the Response time value, which is the special timer mentioned above.
...
Now that we've seen how plugin monitors are made of a combination an XML file that defines the various inputs/outputs and a script performs the actual task of monitoring, Letlet's take a look how these pieces are packaged together, and how Uptime Infrastructure Monitor UIM knows which plugins are available for installinstallation.
Packaging plugins
The best way to understand how Uptime Infrastructure Monitor UIM plugins are packaged is to take a look at the zip file for a plugin itself. We'll use the same Custom Remote Monitor from above as our example again. The actual zip file that is used when installing the plugin is located within this repo's 's dist' folder folder, along with some .upk files (The legacy plugin format used by older versions of Uptime Infrastructure Monitor).
You can easily download the 'the monitor-custom-remote.zip' yourself, and look at the contents directly, but the contents of that archive are just a zipped-up version of the repo's ' pkg ' directory, which you can easily view on GitHub here.
...
The contents of the zip/pkg folder are made up of the xml file that we've already discussed in detail above, and a mix of one or more 'files' folders. These files folders contain the actual scripts that will be extracted into place on the Uptime Infrastructure Monitor UIM monitoring station. The reason for the files-win & and files-posix folders are that plugins may require different files or scripts depending which OS (ie. Windows or Linux) the Uptime Infrastructure Monitor UIM monitoring station is running. As such, the contents of the 'files-win' folder will is extracted only be extracted on Windows monitoring station, and the 'files-posix' folder will is extracted only be extracted on a Linux monitoring station.
| Info |
|---|
As mentioned before, most of the plugins created by Uptime Infrastructure Monitor UIM are intended for cross-platform use. This is why is most of them they have all three of these 'files ' folders. When creating your own plugin monitor, you can focus just on the OS platform of your Uptime Infrastructure Monitor UIM monitoring station, and simplify the packaging of your plugin by placing all of the scripts within the 'files ' folder. |
The mechanism for how these 3 three folders are extracted during the plugin's installation are the same general process whether the monitoring station is running Windows or Linux. Which is that each of the 'files ' folders will be is extracted into the directory where Uptime Infrastructure Monitor UIM is installed on the monitoring station. Any sub-folders within the plguinplugin's 'files ' folders will be is created along the way if they don't already exist. Though in most cases, you'll want to place all your plugin's scripts/files within it's its own sub-folder in uptime_dir/plugins/scripts/.
| Info |
|---|
Another thing you may notice with some of the plugins created by uptime is that they have scripts that go in both the |
So in the case of the Custom Remote Monitor's 'files' folder, you'll notice it contains some sub folders (ie. plugins/scripts/monitor-custom-remote ) which eventually contain a single rcs.php file.
When installed on a Linux monitoring station, those files will end up in a location similar to below. ( In this example, Uptime Infrastructure Monitor UIM was installed in the default default /usruser/local/uptime_location). The 'monitor-custom-remote.sh' file comes from a similar sub-folder within the 'files-posix' folder.
Similarly, on a Windows monitoring station that file would end up in the location similar to below. ( In this example Uptime Infrastructure Monitor , UIM was installed into the default default C:\Program Files\uptime software\upUptime Softwarup.time\[location for Windows)]. The 'monitor-custom-remote.bat' file comes from a similar sub- folder within the plugin's 'files-win' folder.
Extension.json
Now that we've seen how a plugin monitor is packaged into it's own zip file, the last piece we need to look at the extension.json file that the monitoring station uses to know which plugins are available for install and where to get the associated zip files. By default Uptime Infrastructure Monitor will attempt , UIM attempts to get these details from our website at this location: http://the-grid.uptimesoftware.com/extension.json on our website.
In order to install your own plugins for testing, you'll need to create your own copy of this file that includes details about where to locate your own plugin files. The general process for that is outlined in this KB article: How To Install Plugins Without Direct Internet Accessin How to install plugins without direct internet access. Though that article focuses on how to internally mirror the currently available plugins for environments where the Uptime Infrastructure Monitor UIM server doesn't have direct access to the external internet. In our situation, we instead need to use the same general process to create our own extension.json file that lists details about our own plugins.
Each plugin listed will need needs a entry in the json file similar to the below example of the 'Custom Remote Monitor':
...
Most of these fields are pretty self explanatory and match up with similar fields from the monitor's XML file. The most important of these fields is is git_file_target which tells Uptime Infrastructure MonitorUIM's extension manager where to find the zip file it needs to download to install the plugin. Most of the plugins provided by Uptime Infrastructure Monitor UIM have this field pointing to a location on GitHub.com, though that isn't required, and you can place these files anywhere that is accessible from your monitoring station over http.
The next most important fields for a plugin are the 'name' & and 'version' as these are used to figure out which plugins are currently installed within Uptime Infrastructure Monitor UIM and if they're running the current version. A combination of these two fields controls whether a user will see sees the Installed/Install/Upgrade buttons within the extension manager. The contents of the name field in the JSON needs to exactly match the XML's class tag.
...
By now you've hopefully been able to create your own plugin monitor for use with Uptime Infrastructure Monitor and are asking yourself how you can share your creation with other Uptime Infrastructure Monitor UIM users.
Choosing a license
One thing you may not of thought about much more when creating software/scripts for internal project is 'What Copyright License , "What copyright license should I release this under?'"
If your you are not aware, there's a variety of different copyright licensing models available for open source software that outlines what changes someone can make to your code and how can they share it among others. At Uptime Infrastructure Monitor we We recommend using one of the ' Creative Commons ' Licenses as they provide easy to understand descriptions of what the license covers. Details about these licenses are available at: https https://creativecommons.org/licenses/.
Of the licenses listed on the Creative Commons website, we recommend using the Attributionthe Attribution-ShareAlike with plugins as it provides the best fit for how plugins are typically created and expanded upon. Once you've chosen the appropriate license for your plugin, you'll need to mention it somewhere within the plugin itself, typically either as part of the readme itself or by adding a license.txt file to your plugin repo. See this page on GitHub for some common ways people handle this.
...
If you haven't been using git or some other version control tool while creating your plugin then it's time to create a repository for it on GitHub, as that's the easiest way to share your creation with us and make it available for download via the Extension Manager. Here's some documentation on GitHub.com that covers the basics of howto create your own repository and a general introduction for working with git.
Once your plugin is available on GitHub it's time to contact uptimecontact uptime-support@idera.com and let us know about your creation. From there we'll take a look at what your plugin does, and how it works, and do some of the remaining tasks involved in making it available for download via Uptime Infrastructure Monitor's extension manager.