> 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/concepts/telemetry-model.md).

# Telemetry Model

Rumi Management implements a telemetry pipeline that collects runtime metrics from running containers and stores them in a time-series database for dashboarding and alerting.

## Heartbeats

Rumi containers emit **heartbeats** at a configurable interval (default: 5 seconds). Each heartbeat contains a snapshot of the container's runtime state, including:

* **Memory metrics** — Heap and non-heap usage, physical memory, entity counts, pool allocation statistics.
* **Latency metrics** — Messaging latency waypoints, per-transaction latency samples.
* **Thread metrics** — Thread counts and per-thread statistics.
* **GC metrics** — Garbage collection counts and pause times.
* **Application metrics** — Store operations (hit/miss/eviction rates), message counts, disruptor ring buffer statistics, transaction latencies.
* **Custom metrics** — User-defined gauges and counters exposed by application code.

Heartbeats are delivered over the Rumi messaging bus to the Agent.

## Collection Pipeline

The Agent's telemetry pipeline processes heartbeats through the following stages:

```
Container Heartbeat (Rumi Messaging)
       │
       ▼
 XVMHeartbeatCollector
       │
       ▼
 RogNodeToPointTransform (converts ROG nodes to PointData)
       │
       ▼
 PointStore (writes to storage backend)
       │
       ▼
 InfluxDB (time-series database)
```

### XVMHeartbeatCollector

The collector receives heartbeat messages from containers and extracts metrics. It processes:

* Container-level system metrics (CPU, memory, GC, threads).
* Application-level metrics (store operations, message throughput, latency).
* Custom application metrics (user gauges and counters).

### RogNodeToPointTransform

The transform converts Rumi Object Graph (ROG) nodes from the heartbeat data into `PointData` objects suitable for time-series storage. Each point consists of:

* **Measurement name** — Identifies the metric category (e.g., `application`, `system`, `application.store`).
* **Tags** — Indexed dimensions for filtering (e.g., `system_name`, `vm_name`, `app_name`).
* **Fields** — Metric values (e.g., `process_cpu_load`, `memory_heap_used`).
* **Timestamp** — When the measurement was taken.

### PointStore

The `PointStore` is a pluggable storage abstraction with the following implementations:

| Implementation                 | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| **InfluxBatchAwarePointStore** | Writes to InfluxDB with batching for efficiency   |
| **BasicPointStore**            | Generic implementation for other storage backends |
| **StubBatchAwarePointStore**   | Stub for testing                                  |

The storage backend is configured via the `nv.agent.point.store` property (`influx`, `fake_influx`, or `none`).

## InfluxDB Storage

When using InfluxDB, metrics are stored under the `rumi_heartbeat_rp` retention policy. The Agent creates this retention policy and manages the database connection.

For a detailed reference of all InfluxDB measurements, tags, and fields, see the [InfluxDB Measurements Reference](/rumi-management/reference/agent/influxdb-measurements.md).

## Custom Collectors

The telemetry pipeline supports custom collectors via the `XVMHeartbeatCollectorPlugin` interface. Custom collectors can:

* Extract additional metrics from heartbeat data.
* Transform and enrich metrics before storage.
* Write to additional storage backends.

See the [Custom Collectors Guide](/rumi-management/guides/agent/custom-collectors.md) for details on implementing collector plugins.

## Dashboard Consumption

The telemetry data stored in InfluxDB is consumed by Rumi Monitor (Grafana) through pre-built dashboards. Users can also create custom dashboards by querying the InfluxDB measurements directly. The dashboards use template variables for filtering by system, container, application, and host.