In This Section

Overview

 

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:

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

  <dependencies>
    <dependency>
      <groupId>com.neeve</groupId>
      <artifactId>nvx-lumino-agent</artifactId>
      <version>1.5.2</version> <!-- or later -->
      <scope>provided</scope>
    </dependency>
  </dependencies>

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: 

package com.neeve.lumino.example;

import java.util.Map;
import com.neeve.lumino.agent.collectors.plugin.PointDataBuilder;
import com.neeve.lumino.agent.collectors.plugin.XVMHeartbeatCollectorPlugin;
import com.neeve.server.mon.SrvMonHeartbeatMessage;
/**
 * A sample collector plugin. 
 */
public class CollectorPlugin extends XVMHeartbeatCollectorPlugin {
    /**
     * Adds a simple hostname tag to collected heartbeat data points. 
     */
    @Override
    public void addCustomTags(SrvMonHeartbeatMessage heartbeat, Map<String, String> customTags) {
        String hostName = heartbeat.getServerHostName();
        String simpleHostName = hostName;
        if (hostName.indexOf('.') > 0 && Character.isLetter(hostName.charAt(0))) {
            simpleHostName = hostName.substring(0, hostName.indexOf('.'));
        }
        customTags.put("simple_host_name", simpleHostName);
    }

    /**
     * Intercepts gc data points and attempts to classify the collector as minor or major based on collector name. 
     */
    @Override
    public void addPointData(SrvMonHeartbeatMessage heartbeat, String measurementName, PointDataBuilder builder) {
        if (measurementName.equals("system.gc")) {
            if (builder.getTagValue("collector_name").toLowerCase().indexOf("new") >= 0) {
                builder.tag("collection_type", "minor");
            }
            else {
                builder.tag("collection_type", "major");
            }
        }
    }
} 

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. 

## [COLLECTOR CONFIG]
## ==================
## Uncomment the following and specify a comma separated list of plugin classes that 
## extend com.neeve.lumino.agent.collectors.plugin.XVMHeartbeatCollectorPlugin
## to augment hearbeats collected by the agent. The jar for the collector
## should be placed in the data/agent/ext directory and will be made available
## to the agent when it is next deployed or reprovisioned. 
lumino.agent.collectors.heartbeat.plugins=com.neeve.lumino.example.CollectorPlugin

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:

cd /opt/nvx-lumino/current
./stop.sh
./start.sh --reprovision

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:

(inf)...Loaded collector plugin: CollectorPlugin