> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/guides/agent/custom-collectors.md).

# 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](/rumi-management/reference/agent/influxdb-measurements.md)) 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.