In This Section
Overview
SINCE 1.5.2
The Lumino Agent's XVM Heartbeat collector supports the ability for collector plugin classes to be registered that can add additional tags or fields to the measurements being written to influx. This section discusses how plugins can be registered with a Lumino Agent.
Plugin API
Collector plugins must extend the XVMHeartbeatCollectorPlugin class. A collector plugin can override the No-Op methods in the XVMHeartbeatCollectorPlugin class to augment data points written to influx. Two such methods exist:
- addCustomTags: Is called once per heartbeat received by the collector. Any tags added to the provided customTags map will be applied to all points written for that heartbeat.
addPointData: Is called for every measurement written for a given heartbeat, and provided the plugin with the opportunity to add any tags or fields specific to the point being written.
See the Lumino Agent plugin javadoc for additional details
Building Plugins
If you are using maven to build a plugin, simply include nvx-lumino-agent as a dependency to your project
Otherwise, download the latest nvx-lumino-agent distribution (see the release notes page) and use the agent's jars folder as your project's dependencies.
Plugin Example
The following class shows an example of a collector plugin. The plugin below adds a custom tag, simple_host_name, to all data points written to influx, and also attempts to tag gc statistics as being either a major or minor gc:
Configuring Agents with Plugins
To register a plugin with a given Lumino Agent, the plugin must be packaged in a jar that is included on the agent's classpath, and the agent's robin.conf needs to be updated to specify the plugin's fully qualified classname.
Adding Plugins to the Agent Classpath
To add a plugin to the agent's classpath, the plugin should be packaged in a jar, and placed in the agent's <lumino-install-root>/data/agent/ext folder.
If upgrading from an older version or on a fresh agent install, the data/agent/ext folder does not exist, it should be created manually.
Adding Plugins to robin.conf
When the agent is started it loads plugins configured via the property lumino.agent.collectors.heartbeat.plugins which can be specified in the agent's robin.conf file. The robin.conf file can be found in the <lumino-install-root>/data/robin folder after the agent has been launched for the first time.
<lumino-install-root>/data/robin/robin.conf
On a fresh installation of Lumino, the robin.conf file will not yet have been copied to the data/robin folder. Consequently, the agent needs to be launched once prior to adding plugins.
The Lumino agent needs to be restarted and reconfigured after updating either the jars in the ext folder or the plugin configuration in robin.conf. Once a plugin is configured the agent should be stopped and restarted with the '–reprovision' flag. For example, if lumino is installed to /opt/nvx-lumino:
Verifying Plugin Was Loaded
If the plugin was configured correctly and loaded by the agent, the following should be logged in the lumino.agent log:
data/agent/logs/lumino.agent.log.0