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:

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

Environment Variables:

export nv_stats_memory_enable=true
export nv_stats_memory_type_enable=false

DDL <env> Section (highest precedence):

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

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.

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.

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.

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:

nv.stats.memory.interval=5

Environment Variables:

export nv_stats_memory_interval=5

DDL <env> Section (highest precedence):

<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.

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.

Related Topics

• Memory Statistics - Understanding and interpreting memory metrics

• Container Heartbeats - Configure container-level heartbeat emission

• Engine Statistics - Configure AEP engine statistics collection

• Coding for Zero Garbage - Techniques for zero-garbage operation

• Tuning Pools - Pool configuration and tuning