Master Java Metaspace: Tuning Metadata GC Threshold and JVM Flags

1 Overview

This article explores Metaspace and the Metadata GC Threshold in the JVM, and explains how to adjust these parameters for better memory management.

2 Metadata

Metadata stores information about objects in the heap, such as class definitions and method tables. Depending on the Java version, the JVM keeps this data in the Permanent Generation (PermGen) or in Metaspace.

The JVM relies on metadata to perform class loading, bytecode verification, and dynamic binding.

3 PermGen and Metaspace

Since Java 8, the JVM replaces PermGen with a new memory region called Metaspace to store metadata.

PermGen is a fixed‑size region separate from the main heap; when it fills up, the JVM throws an OutOfMemoryError.

Metaspace can grow dynamically based on the amount of metadata used and is allocated from native memory, limited only by the host OS.

4 Metadata GC Threshold

When a metadata object is created, it occupies memory like any other object, but the JVM does not collect metadata until a certain size threshold is reached.

As more classes are loaded at runtime, Metaspace gradually fills up.

The JVM defines a threshold for Metaspace size; when an allocation would exceed this threshold, a metadata garbage‑collection cycle is triggered.

5 JVM Flags for Metadata

Flags such as -XX:+PrintClassHistogram and -XX:+PrintMetaspaceStatistics can be used to gather statistics about class metadata usage and to print Metaspace details.

These statistics help developers tune code and JVM parameters to improve Metaspace usage and GC behavior.

5.1 -XX:MetaspaceSize=<size>

Sets the initial amount of space allocated for class metadata (the initial high‑water mark, in bytes). The JVM may increase or decrease this size automatically.

A larger value reduces the frequency of metadata GC cycles. The default varies by platform, typically between 12 MB and 20 MB.

Example (set to 128 MB):

-XX:MetaspaceSize=128m

5.2 -XX:MaxMetaspaceSize=<size>

Defines the maximum size Metaspace can grow to; exceeding this limit results in an OutOfMemoryError.

By default there is no explicit limit, allowing Metaspace to expand up to the available native memory.

Example (set to 100 MB):

-XX:MaxMetaspaceSize=100m

5.3 -XX:+UseCompressedClassPointers

Enables compressed class pointers on 64‑bit JVMs, allowing class metadata to be addressed with 32‑bit pointers instead of full 64‑bit pointers, reducing memory consumption.

This optimization separates class space from non‑class space, creating two global Metaspace contexts: one for Klass structures and one for everything else.

Modern 64‑bit JVMs enable this flag by default, so explicit configuration is usually unnecessary.

5.4 -XX:+UseCompressedOops

Enables compressed ordinary object pointers (Oops) on 64‑bit JVMs, using 32‑bit references for Java objects, which saves memory and can improve performance.

Compressed Oops can address only a limited memory range, forcing the JVM to use smaller pointers.

6 Conclusion

The article covered the concepts of metadata and Metaspace, explained why metadata GC thresholds are triggered, and presented several JVM flags that can be tuned to control Metaspace size and improve garbage‑collection efficiency.

In the next session, a real‑world OOM case caused by Metaspace will be examined.