Custom Collectors

This guide covers writing custom heartbeat collector plugins for the Rumi Agent.

Overview

The Agent's telemetry pipeline is extensible through the XVMHeartbeatCollectorPlugin interface. Custom collectors can extract additional metrics from heartbeat data, transform or enrich metrics, and write to additional storage backends.

The Collector Plugin Interface

Custom collectors implement the XVMHeartbeatCollectorPlugin interface, which provides hooks into the heartbeat collection lifecycle.

A collector plugin can:

• Receive raw heartbeat data from containers.

• Extract custom metrics from the heartbeat payload.

• Transform data into PointData objects for time-series storage.

• Write metrics to the configured PointStore (InfluxDB) or to custom storage backends.

Building a Custom Collector

Implementation Steps

1. Implement the interface — Create a class implementing XVMHeartbeatCollectorPlugin.

2. Extract metrics — Process the heartbeat ROG (Rumi Object Graph) nodes to extract the metrics you need.

3. Build points — Use the PointDataBuilder fluent API to construct PointData objects with the appropriate measurement name, tags, and fields.

4. Register the plugin — Configure the Agent to load your collector plugin.

Building PointData

The PointDataBuilder provides a fluent API for constructing time-series data points:

• Set the measurement name to categorize the metric.

• Add tags for indexed dimensions (system name, container name, application name, etc.).

• Add fields for metric values.

• Set the timestamp.

Data Model Considerations

When designing custom measurements:

• Use tags for dimensions you will filter or group by (low cardinality).

• Use fields for metric values (high cardinality is acceptable).

• Follow the existing naming conventions (see InfluxDB Measurements Reference) for consistency with canned dashboards.

Deployment

Package the custom collector as a JAR and include it in the Agent's classpath. Configure the Agent to load the plugin at startup.