Understanding Memory Usage in HiveMQ Deployments

1 Purpose
2 Why does “used” memory grow even when the JVM heap is flat?
3 Quick glossary
4 How to read the graphs
5 Sizing guidelines
6 Kubernetes best practices
7 When to act (and when not to)
8 FAQ
9 Further reading
10 Need deeper help?

Purpose

Help HiveMQ users correctly interpret memory‑related metrics, avoid misdiagnosing healthy cache growth as a leak, and configure their clusters for safe, efficient operation.

Why does “used” memory grow even when the JVM heap is flat?

Linux aggressively repurposes spare RAM for filesystem page‑cache and buffers, then frees it on demand. HiveMQ also allocates off‑heap memory for native components such as its persistence cache, network buffers, and direct ByteBuffers. When the MQTT workload is light, these layers naturally expand while the JVM heap remains stable.

Quick glossary

Layer	Metric / dashboard field	Reclaimed automatically?	Typical contents

Layer	Metric / dashboard field	Reclaimed automatically?	Typical contents
JVM heap	`JVM Heap Used / Committed`	Garbage‑collected	MQTT messages, plug‑in objects
Native / off‑heap	Part of RSS (Resident Set Size)	No (must fit inside pod limit)	Persistence cache, direct buffers, Netty arenas
Page cache	Lowers Free but not Available	Yes (kernel)	Frequently accessed data files, binaries
Free	`free -m` → free	N/A	Truly unused RAM
Available	`free -m` → available	N/A	Free + reclaimable cache – primary pressure signal

How to read the graphs

Watch Available RAM, not Free. Available > 20 % ⇒ safe; < 5 % ⇒ investigate.
Compare JVM heap vs RSS. If the heap is flat but RSS climbs slowly, you are usually seeing cache growth, not a leak.
Look for GC/OOM events. Genuine leaks surface as increasing GC time, OutOfMemoryError, or pod restarts.

Sizing guidelines

Rule of thumb: set the JVM heap to ≈ 50 % of node RAM.

Node RAM	Example `JVM_HEAP`	Why
4 GiB	2 GiB	Leaves head‑room for native layers
8 GiB	4 GiB	Recommended staging setup
16 GiB	8 GiB

Native caches and buffers usually settle around 10‑15 % of RAM, scaling automatically with available memory.

Kubernetes best practices

Always set resources.requests and resources.limits for CPU and memory on every HiveMQ pod.
Enable the MemoryPressure eviction signal so Kubernetes moves pods before the kernel performs an OOM kill.
Keep heap + native usage below the pod limit. A 50 / 50 split is a robust starting point.

When to act (and when not to)

Symptom	Likely cause	Recommended action
JVM heap steady, RSS rises slowly, Available > 20 %	Page cache / native caches	Do nothing – expected behaviour.
JVM heap grows to limit, frequent GC pauses, Available still high	Heap too small for workload	Increase heap or optimise load.
Available < 5 % and dropping	Real memory pressure	Review pod limits, scale out, inspect native usage.
OOM‑kills / pod restarts	Hard exhaustion	Capture diagnostics; open a Support Request.

FAQ

Why did free memory drop after upgrading HiveMQ?
A newer base image or kernel can make Linux cache more aggressively. If Available memory remains high, no action is required.

Is it safe to restart pods just to “free” RAM?
Restarting only clears caches and prolongs warm‑up; Linux automatically reclaims memory when needed.

How can I inspect off‑heap usage?
Compare kubectl top pod (RSS) with JVM heap; the difference approximates native usage.

Need deeper help?

Send us a diagnostic archive and heap dump, and open a Support Request referencing this KB.