> For the complete documentation index, see [llms.txt](https://docs.xplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplatform.com/talon/developing-applications/configuring-the-runtime/monitoring/xvm-heartbeats.md). # XVM Heartbeats Configure periodic XVM-level statistics emission from your XVM. ## Overview XVM heartbeats provide periodic snapshots of XVM-level statistics including system metrics, thread statistics, pool usage, engine stats, and application-defined stats. Heartbeats can be emitted via messaging, logged to binary transaction logs, or traced for debugging. Statistics collection must be balanced against performance impact. While many statistics have minimal overhead, enabling all collection options can impact latency-sensitive applications. ## Heartbeat Configuration Heartbeats for an XVM can be enabled via DDL using the `` element: ```xml true true true false 100000000 false true 1.0 ``` ## Configuration Settings | Configuration Setting | Default | Description | | ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | false |

Enable or disable XVM stats collection and heartbeat emission.


Performance Impact: Collection of stats and emission of heartbeats can impact application performance from both a latency and throughput standpoint. For applications that are particularly sensitive to performance, it is a good idea to compare performance with and without heartbeats enabled to understand the overhead that is incurred by enabling heartbeats.

| | `interval` | 1000 | The interval in seconds at which XVM stats will be collected and emitted | | `collectNonZGStats` | true | Some statistics collected by the stats collection thread require creating a small amount of garbage. This can be set to false to suppress collection of these stats | | `collectIndividualThreadStats` | true | Indicates whether heartbeats will contain stats for each active thread in the JVM. Individual thread stats are useful for identifying busy threads and thread affinitization candidates | | `collectSeriesStats` | true | Indicates whether or not series stats should be included in heartbeats | | `collectSeriesDatapoints` | false |

Indicates whether or not series stats should report the data points captured for a series statistic.


Warning: Enabling this value includes each datapoint collected in a series in heartbeats which can make emitted heartbeats very large and slow down their collection. It is not recommended that this be run in production.

| | `maxTrackableSeriesValue` | 10 minutes | The maximum value (in **microseconds**) that can be tracked for reported series histogram timings. Datapoints above this value will be downsampled to this value, but will be reflected in the max value reported in an interval | | `includeMessageTypeStats` | false |

Sets whether or not message type stats are included in heartbeats (when enabled for the app).

When captureMessageTypeStats is enabled for an app, the AEP engine will record select statistics on a per message type basis. Because inclusion of per message type stats can significantly increase the size of heartbeats, inclusion in heartbeats is disabled by default.


Tip: For message type stats to be included in heartbeats, both captureMessageTypeStats for the app must be set to true (capture is disabled by default because recording them is costly), and includeMessageTypeStats must be set to true (inclusion is disabled by default because emitting them is costly).

| | `collectPoolStats` | true | Indicates whether or not pool stats are collected by the XVM | | `poolDepletionThreshold` | 1.0 |

Configuration property used to set the percentage decrement at which a preallocated pool must drop to be included in an XVM heartbeat. Setting this to a value greater than 100 or less than or equal to 0 disables depletion threshold reporting.

This gives monitoring applications advanced warning if it looks like a preallocated pool may soon be exhausted. By default the depletion threshold is set to trigger inclusion in heartbeats at every 1% depletion of the preallocated count. This can be changed by specifying the configuration property nv.server.stats.pool.depletionThreshold to a float value between 0 and 100.

Example: If a pool is preallocated with 1000 items and this property is set to 10, pool stats will be emitted for the pool each time a heartbeat occurs and the pool has dropped below a 10% threshold of the preallocated size (e.g., at 900, 800, 700, until its size reaches 0).

| | `logging` | *See below* |

Configures binary logging of heartbeats.

Binary heartbeat logging provides a means by which heartbeat data can be captured in a zero garbage fashion. Collection of such heartbeats can be useful in diagnosing performance issues in running apps

| | `tracing` | *See below* |

Configures trace logging of heartbeats.

Enabling textual tracing of heartbeats is a useful way to quickly capture data from XVM heartbeats for applications that aren't monitoring XVM heartbeats remotely. Textual trace of heartbeats is not zero garbage and is therefore not suitable for applications that are latency sensitive

| ## Trace Output Configuration By default all XVM statistics tracers are disabled as trace logging is not zero garbage and introduces CPU overhead. While tracing heartbeats isn't recommended in production, enabling XVM statistics trace output can be useful for debugging and performance tuning. ```xml true true true true true ``` ## Binary Logging Configuration Applications that are latency sensitive might prefer to leave all tracers disabled to avoid unnecessary allocations and the associated GC activity. As an alternative, it's possible to enable logging of zero-garbage heartbeat messages to a binary transaction log: ```xml /path/to/heartbeat/log/directory ``` When a `storeRoot` is not set, an XVM will log heartbeats to `{XRuntime.getDataDirectory}/server-heartbeats/-heartbeats.log`, which can then be queried and traced from a separate process using the [Stats Dump Tool](/talon/operating-applications/analysis-and-troubleshooting/tools/stats-dump-tool.md). {% hint style="warning" %} **Warning**: At this time binary heartbeat logs do not support rolling collection. Consequently this mechanism is not suitable for long running application instances. {% endhint %} ## Memory Stats Configuration In addition to the JVM heap and non-heap memory shown in the system stats section of heartbeats, Talon can collect detailed off-heap memory, IO buffer, and ADM entity lifecycle statistics. These are included in heartbeat messages and can also be traced independently. | Property | Default | Description | | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nv.memory.stats.enable` | `false` | Enable detailed memory stats collection (off-heap, IO buffer, entity tracking). Must be set to `true` for memory stats to appear in heartbeats and standalone trace | | `nv.memory.stats.type.enable` | `false` | Enable per-entity-type breakdown. When enabled, memory stats include counters for each individual message, entity, embedded entity, and collection type | | `nv.memory.stats.interval` | `0` | Standalone memory stats trace interval in seconds. When set to a value greater than 0, memory stats are traced to the `nv.memory.stats` logger independently of heartbeats. Useful for debugging memory issues without enabling full heartbeats | These properties can be set as system properties or in DDL: ```xml true true ``` {% hint style="info" %} **See Also**: [Memory Stats](/talon/operating-applications/monitoring/memory-statistics.md) for a complete reference of all memory statistics collected and their meaning. {% endhint %} ## Related Topics * [XVM Heartbeats](/talon/operating-applications/monitoring/xvm-heartbeats.md) - Viewing and interpreting heartbeat statistics at runtime * [Memory Stats](/talon/operating-applications/monitoring/memory-statistics.md) - Detailed memory statistics reference * [Engine Statistics](/talon/developing-applications/configuring-the-runtime/monitoring/engine-statistics.md) - Configure engine-level statistics collection * [Stats Dump Tool](/talon/operating-applications/analysis-and-troubleshooting/tools/stats-dump-tool.md) - Analyzing binary heartbeat logs * [Operating Model](/talon/concepts-and-architecture/operating-model.md) - Monitoring architecture overview ## Next Steps 1. Enable heartbeats with appropriate collection settings 2. Test performance impact under load 3. Configure binary logging for zero-garbage collection or tracing for debugging 4. Set up monitoring tools to consume heartbeats 5. Balance operational visibility against performance requirements