Skip to main content
Migration Notice
We're migrating documentation from the old portal into this one. Some things may look a little different or out of place in the meantime — we know, and we're working to get it right. If something's unclear or doesn't look right, let us know.

Agent Dashboard — JVM Heap Used

What this chart shows​

JVM Heap Used % is the percentage of the JVM's configured maximum heap that live objects currently occupy. The agent reports it on every heartbeat.

The denominator is -Xmx, the JVM maximum heap. A value of 80% means the copy engine is using 80% of its heap allocation.

Polling interval​

The agent samples heap use on each heartbeat. A heartbeat fires every 30 seconds plus a random offset of 0–10 seconds, so chart points are about 30–40 seconds apart.

The random offset keeps all agents from writing to ClickHouse at the same moment.

Each point is the heap occupancy at that instant. Post-GC dips appear as V-shaped drops.

How to read it​

Value rangeInterpretation
0–60%Healthy. Plenty of GC headroom.
60–80%Moderate pressure. GC runs more frequently.
80–90%High. Watch for GC pauses that affect throughput. Alarm AG-008 is raised when heapPct > 85.
>90%Critical. Risk of OutOfMemoryError. A heap dump is written to data/oom-heap.hprof.

OOM protection​

The agent JVM runs with -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=data/oom-heap.hprof.

If heap use reaches 100% and GC cannot reclaim enough memory, the JVM writes a heap dump and exits. The copy engine restarts automatically. The console marks any in-flight jobs as failed so that you can resubmit them.

Tuning​

The JVM profile assigned to the agent controls its heap allocation.

  • Define profiles in Setup & Settings > Diagnostics > JVM Profiles.
  • Assign a profile with the agent's Profile picker on the Live Agents tab.
  • The sizing guide on the Agent Installation tab lists the profiles.

The Default (8 GB host) profile runs -Xmx6g. If heap pressure is chronic, give the agent a bigger host and assign the matching profile:

  • 16 GB Host (-Xmx12g)
  • 24 GB Host (-Xmx18g)
  • Larger profiles, up to 64 GB Host (-Xmx48g)