> 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-core/guides/developing-applications/configuring-the-runtime/monitoring/memory-statistics.md).

# Memory Statistics

Configure memory statistics collection for monitoring heap, off-heap, native memory, IOBuffer, and entity object usage.

## Overview

Rumi tracks detailed memory usage statistics across several categories: JVM heap and non-heap memory, off-heap memory managed by the platform, native memory allocations, IOBuffer lifecycle, and entity/message/collection object management. These stats are collected by the `MemoryStats` singleton and can be consumed in two ways: via standalone periodic trace output, or as part of container heartbeat messages.

## Enabling and Disabling Memory Stats

Memory stats collection is controlled by environment properties. These can be specified via any of the supported configuration sources (in increasing precedence order):

**System Properties:**

```
-Dnv.stats.memory.enable=true
-Dnv.stats.memory.type.enable=false
```

**App Property File:**

```properties
nv.stats.memory.enable=true
nv.stats.memory.type.enable=false
```

**Environment Variables:**

```bash
export nv_stats_memory_enable=true
export nv_stats_memory_type_enable=false
```

**DDL `<env>` Section** (highest precedence):

```xml
<env>
  <nv>
    <stats>
      <memory>
        <enable>true</enable>
        <type>
          <enable>false</enable>
        </type>
      </memory>
    </stats>
  </nv>
</env>
```

{% hint style="info" %}
The `nv.stats.memory.*` property namespace is the preferred configuration mechanism. The `nv.memory.stats.*` variants (e.g., `nv.memory.stats.enable`, `nv.memory.stats.type.enable`) are also supported for backward compatibility.
{% endhint %}

### Properties Reference

| Property                      | Default | Description                                                                                                                                                                     |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nv.stats.memory.enable`      | `true`  | Enables or disables memory stats collection entirely. When disabled, no memory counters are updated.                                                                            |
| `nv.stats.memory.type.enable` | `false` | Enables per-type entity stats collection. When enabled, counters are tracked individually for each entity, message, and collection class in addition to the aggregate counters. |

{% hint style="warning" %}
**Performance Impact**: Enabling per-type stats (`nv.stats.memory.type.enable=true`) adds synchronization overhead for each entity allocation/disposal and should be used with caution.
{% endhint %}

## Standalone Memory Stats Trace

Memory statistics can be output independently of container heartbeats by configuring the standalone memory stats logger. This is useful for debugging memory issues or monitoring memory behavior in development and testing without enabling full container heartbeats.

### Enabling Standalone Trace

Enable periodic trace output by setting the `nv.stats.memory.interval` property to the desired interval in seconds. This can be specified via any of the supported configuration sources (in increasing precedence order):

**System Properties:**

```
-Dnv.stats.memory.interval=5
```

**App Property File:**

```properties
nv.stats.memory.interval=5
```

**Environment Variables:**

```bash
export nv_stats_memory_interval=5
```

**DDL `<env>` Section** (highest precedence):

```xml
<env>
  <nv>
    <stats>
      <memory>
        <interval>5</interval>
      </memory>
    </stats>
  </nv>
</env>
```

This starts a background thread (`X-Stats-Logger [nv.memory.stats]`) that periodically outputs memory stats to the `nv.memory.stats` tracer at `INFO` level.

| Property                   | Default        | Description                                                                                                        |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `nv.stats.memory.interval` | `0` (disabled) | The interval in seconds at which standalone memory stats trace is emitted. A value of 0 disables standalone trace. |

{% hint style="info" %}
**Note**: The standalone memory stats trace is independent of container heartbeats. Both can be enabled simultaneously, but they serve different purposes: standalone trace provides a quick, lightweight view of memory behavior, while heartbeats provide the full container statistics picture and can be consumed programmatically.
{% endhint %}

## Related Topics

* [Memory Statistics](/rumi-core/guides/operating-applications/monitoring/memory-statistics.md) - Understanding and interpreting memory metrics
* [Container Heartbeats](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring/xvm-heartbeats.md) - Configure container-level heartbeat emission
* [Engine Statistics](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring/engine-statistics.md) - Configure AEP engine statistics collection
* [Coding for Zero Garbage](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/coding-for-zero-garbage.md) - Techniques for zero-garbage operation
* [Tuning Pools](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/coding-for-zero-garbage/tuning-pools.md) - Pool configuration and tuning