If we don't have a native plugin available for what you'd like to monitor, you can create a custom plugin. These are Python files. If you can get the value or metric from your server/application, it can be sent to Server Density to be monitored, graphed and alerted on.
This method only applies to the v1 agent. Please see the custom plugin documentation for the v2 agent.
Using Windows or agent v1? Read the docs.
Configure the agent for custom plugins
Plugin support in the agent is disabled by default. To enable it, you need to do the following steps.
Create a plugin directory
This is a single directory anywhere on your server which will contain your plugin scripts. Make sure it has the correct permissions so it is accessible by the agent. For example, you can create the directory in /usr/local/sd-agent-plugins
Tell the agent where the directory is
Open the agent config.cfg file. This is located at /etc/sd-agent/config.cfg or if you didn't use our installer, where you downloaded the agent to. Edit the following line, adding the full absolute path to your plugin directory. Do not include a trailing slash.
plugin_directory: /usr/local/sd-agent-plugins
Optional: configure plugins.cfg
The file plugins.cfg at /etc/sd-agent/plugins.cfg (or if you didn't use our installer, where you downloaded the agent to) should be used to configure settings for any custom plugins if required. plugins.cfg is ignored if a plugins.d folder is found.
Optional: configure plugins.d/
The files in /etc/sd-agent/plugins.d (or if you didn't use our installer, where you downloaded the agent to) can be used for individual configuration files for your plugins if required. Configuration files must fit the search pattern *.cfg. If a plugins.d folder is found, plugins.cfg is ignored.
Writing a custom plugin
Requirements
- Plugins must be written in Python (v2.4+).
- Plugins must be within their own self contained file, but can include other files.
- Plugins files must be a .py file - the filename should be unique to identify the plugin in your account.
- Plugins must have a class named the same as the filename. The class must have a constructor that takes three arguments - the agent configuration object, a logging instance and the raw config. The class must have at least a
run()function which must return a dictionary.
Filename
The filename is used to match with the plugin class, so the agent can dynamically detect new plugins. This simply means naming the file the same as the class name you pick. E.g. if you wanted to create a plugin called New Users your plugin file must be called NewUsers.py. This is then placed inside the plugins directory previously created.
Structure
The script must have a run() function which returns a dictionary. This needs to belong to a class named the same as the filename. The agent will import the script and then immediately call the run() function, using the return value as part of the postback payload. You can, of course, create other classes and functions to do anything you like. The agent will only call run() from the class named the same as the plugin internal name.
The plugin is only imported and the object created once when the agent starts. For every other check cycle, the run() method will be called on the existing object.
Privileges
All plugins on Linux execute as the sd-agent user which is a regular, unprivileged user. Some commands in your plugin may need sudo access which is explained separately.
Return value
Each plugin will be displayed in the interface on a single graph. However, the return dictionary may contain any number of key/value pairs and these will appear as separate series on the graphs.
The name of the key will be what is displayed on the chart and can contain any character except a dot. The value is expected to be an integer or float, although it will be stored as a string and displayed to 4DP on the graphs.
We recommend returning integer or float values instead of strings. This allows us to maintain a history for the metric (Strings are checked for alert conditions and then discarded). It is also important to note that metrics must be smaller than a single precision float (4B) to be accepted by our metrics backend.
Example
For example, the following function for the plugin called Plugin1 and the filename name Plugin1.py - it returns two fixed value key/pairs:
class Plugin1 (object):
def __init__(self, agentConfig, checksLogger, rawConfig):
self.agentConfig = agentConfig
self.checksLogger = checksLogger
self.rawConfig = rawConfig
def run(self):
data = {'hats': 5, 'Dinosaur Rex': 25.4}
return data
agentConfig is the core config (config.cfg) that is read and modified by the agent.
rawConfig is a multi-dictionary that is essentially a clone of the entire plugin config (plugins.cfg or plugins.d/*.cfg) file. This is useful if you want to add custom config values for your plugins.
Plugin Configurations
Plugin configuration files should be structured as follows:
[PluginName] key: value
It's important that all key names are lowercase when referenced in both the plugin and the plugin configuration file, else you may receive key errors on plugin execution.
Finally
Once you have written the script and it exists in the plugin directory, just restart the agent and it will immediately be picked up and executed.
Logging & troubleshooting
Any custom plugin metrics will be visible within the "Plugins" tab of a device.
The agent will also log to various log files in /var/log/sd-agent, so you should check there if you're seeing any trouble. If you contact support, we'll also ask for these logs.
Additional support
If you have any problems using custom plugins, submit a ticket or email hello@serverdensity.com.
Comments