JVMオプション一覧｜Xmx・Xms・GCログ設定をJava 21対応で

JVMオプションとは、java コマンドに渡してヒープサイズ・GCの種類・ログ・障害時の動作などを決める起動引数です。-Xmx（最大ヒープ）と -Xms（初期ヒープ）が代表で、ほかに GC の選択、GC ログ、メモリ不足時のヒープダンプなどを指定します。

この記事では、用途別のオプション一覧表、Java 8 の書き方から Java 11 以降への書き換え表、既定値の実測（PrintFlagsFinal）、小さいヒープで OutOfMemoryError を起こして GC ログとヒープダンプを取る手順を、OpenJDK 21.0.10 で実行した結果つきでまとめました。Java 25 での違いは公式ドキュメントで確認して注記しています。

実行環境：OpenJDK 21.0.10（Ubuntu 24.04）、2 CPU、コンテナのメモリ上限 5.84GB（cgroup v1）。既定値は CPU 数とメモリ量で変わるため、数値は「この環境での例」として読んでください。

JVMオプションの早見表（用途別）

オプションの3つの種類と読み方

JVMオプションは、書き方で「標準」「-X（非標準）」「-XX（詳細）」の3種類に分かれます。

-XX の真偽値は + で有効、- で無効（-XX:+UseZGC、-XX:-UseContainerSupport）、数値は = で指定します。サイズは k・m・g の単位が使えます（-Xmx512m、-Xmx2g）。

既定値を実測する（PrintFlagsFinal と jcmd）

java -XX:+PrintFlagsFinal -version

-XX:+PrintFlagsFinal は、そのマシンで JVM が実際に使う全フラグの最終値を表示します。オプションなしで実行し、主要な行を抜き出した結果です。

java -XX:+PrintFlagsFinal -version | grep -E ' (MaxHeapSize|InitialHeapSize|MaxRAMPercentage|UseG1GC|ThreadStackSize|MaxMetaspaceSize|UseContainerSupport) '

   size_t InitialHeapSize                          = 98566144                                  {product} {ergonomic}
   size_t MaxHeapSize                              = 1568669696                                {product} {ergonomic}
   size_t MaxMetaspaceSize                         = 18446744073709551615                      {product} {default}
   double MaxRAMPercentage                         = 25.000000                                 {product} {default}
     intx ThreadStackSize                          = 1024                                   {pd product} {default}
     bool UseContainerSupport                      = true                                      {product} {default}
     bool UseG1GC                                  = true                                      {product} {ergonomic}

{ergonomic} の値は、CPU 数やメモリ量で変わります。開発機と本番機でヒープが違う原因はここにあるので、本番と同じ環境で確認するのが確実です。人が読みやすい形なら java -XshowSettings:vm -version で Max. Heap Size (Estimated): 1.46G、-XshowSettings:system で Memory Limit: 5.84G のようにコンテナの上限も表示できました。

オプションを変えたときのヒープと GC（実測）

同じマシンで、オプションだけを変えて MaxHeapSize などを比べた結果です。

ここからわかることは4つです。

1. コンテナでは、物理メモリではなくコンテナの上限を基準にヒープが決まります（UseContainerSupport は既定で true）。
2. -Xmx と MaxRAMPercentage を両方書くと -Xmx が優先されます。
3. メモリが小さい環境では MinRAMPercentage（既定50%）が使われ、割合が大きくなります。
4. CPU が1つと判断されると、GC は G1 ではなく Serial が自動で選ばれます。コンテナに CPU を1つだけ割り当てると GC が変わるのはこのためです。

実行中のプロセスを jcmd で確認する

起動済みの JVM の設定は jcmd で確認できます。-Xms256m -Xmx256m -XX:+UseZGC と JFR を付けて起動したプロセスに対する実行結果です。

jcmd -l                     # 起動中の JVM 一覧
jcmd <pid> VM.flags         # 実際に効いているフラグ
jcmd <pid> VM.command_line  # 起動時の引数
jcmd <pid> GC.heap_info     # ヒープの使用状況

$ jcmd -l
13236 Server
$ jcmd 13236 VM.flags
13236:
-XX:CICompilerCount=2 -XX:+FlightRecorder -XX:InitialHeapSize=268435456 -XX:MaxHeapSize=268435456 -XX:MinHeapDeltaBytes=2097152 -XX:MinHeapSize=268435456 ... -XX:-UseCompressedOops -XX:+UseFastUnorderedTimeStamps -XX:+UseZGC -XX:-ZUncommit
$ jcmd 13236 VM.command_line
VM Arguments:
jvm_args: -Xms256m -Xmx256m -XX:+UseZGC -XX:StartFlightRecording=duration=30s,filename=rec.jfr
java_command: Server
$ jcmd 13236 GC.heap_info
 ZHeap           used 40M, capacity 256M, max capacity 256M
 Metaspace       used 4007K, committed 4224K, reserved 1114112K

VM.flags には JVM が自動で追加した値も含まれます。ZGC では -XX:-UseCompressedOops が自動で設定されているのがわかります。jcmd <pid> VM.flags -all なら PrintFlagsFinal と同じ形式で全フラグが見られ、この環境では ZGenerational = false {default} と表示されました（Java 21 の ZGC は既定で非世代別。後述）。

ヒープ・メモリのオプション

ヒープ以外のメモリ（メタスペース、スタック×スレッド数、コードキャッシュ、ダイレクトバッファ）もプロセスのメモリに含まれます。そのため、コンテナのメモリ上限いっぱいに -Xmx を設定すると、合計が上限を超えてコンテナが強制終了されることがあります。ヒープはコンテナ上限の 50〜75% にして、残りをヒープ以外に回すのが目安です。

-Xss とスタックの深さ（実測）

再帰を StackOverflowError まで続け、到達した深さを比べました。

public class Depth {
    static int depth = 0;
    static void recurse() { depth++; recurse(); }
    public static void main(String[] args) {
        try { recurse(); } catch (StackOverflowError e) { System.out.println("depth=" + depth); }
    }
}

-Xss256k: depth=3644
-Xss512k: depth=10198
-Xss1m: depth=22275
-Xss4m: depth=141446

スタックを小さくすると、1スレッドあたりのメモリは減りますが、深い再帰で StackOverflowError になりやすくなります。深さは JIT の状態でも変わるので目安です。スレッドを大量に作るアプリでは -Xss を小さくする選択肢がありますが、Java 21 なら仮想スレッドを使う方法もあります（「Java 仮想スレッド入門」記事を参照）。

GC の選び方とオプション

各 GC を -Xlog:gc 付きで起動したときの1行目です。

[-XX:+UseSerialGC]    [0.004s][info][gc] Using Serial
[-XX:+UseParallelGC]  [0.004s][info][gc] Using Parallel
[-XX:+UseG1GC]        [0.004s][info][gc] Using G1
[-XX:+UseZGC]         [0.018s][info][gc] Using The Z Garbage Collector
[-XX:+UseShenandoahGC][0.007s][info][gc] Using Shenandoah

迷ったら既定の G1 のままにし、GC ログで停止時間を確認してから変えるのが確実です。G1 の主な調整は -XX:MaxGCPauseMillis（停止時間の目標、既定200ms）くらいで、多くの場合はヒープサイズを適切にするだけで十分です。

GC ログの設定（-Xlog:gc*）

Java 9 以降の書き方

Java 9 以降、GC ログは統合ログ（Unified Logging）の -Xlog で指定します。形式は -Xlog:対象:出力先:装飾:出力オプション です。

java -Xlog:gc*:file=/var/log/app/gc-%p-%t.log:time,uptime,level,tags:filecount=5,filesize=10m -jar app.jar

装飾には time、utctime、uptime、timemillis、uptimemillis、pid、tid、level、tags などがあり、java -Xlog:help で一覧を表示できます。

Java 8 からの書き換え表

Java 8 の GC ログ用オプションの多くは、Java 21 では使えません。実際に Java 21.0.10 に渡した結果をあわせて載せます。

（未実行）の行は、Oracle の java コマンド公式ドキュメントの変換表に沿って記載しています。警告と起動エラーの実際の出力です。

$ java -XX:+PrintGCDetails -version
[0.001s][warning][gc] -XX:+PrintGCDetails is deprecated. Will use -Xlog:gc* instead.

$ java -Xloggc:old.log -version
[0.000s][warning][gc] -Xloggc is deprecated. Will use -Xlog:gc:old.log instead.

$ java -XX:+PrintGCDateStamps -version
Unrecognized VM option 'PrintGCDateStamps'
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

$ java -XX:MaxPermSize=256m -version
Unrecognized VM option 'MaxPermSize=256m'
Error: Could not create the Java Virtual Machine.

Java 8 時代の起動スクリプトをそのまま使うと、JVM が起動しないことがあります。移行時は java <オプション> -version で1つずつ確かめ、上の表で書き換えます。-XX:+IgnoreUnrecognizedVMOptions で未知のオプションを無視させることもできますが、設定が効いていないことに気づきにくくなるため、書き換える方が確実です。

OutOfMemoryError を起こして GC ログとヒープダンプを取る

ここでは、わざと小さいヒープ（64MB）でメモリ不足を起こし、GC ログとヒープダンプが取れることを確かめます。本番で同じ設定をしておけば、問題が起きたときに原因を調べる材料が残ります。メッセージ別の原因と対処は「Java OutOfMemoryErrorの原因と対処」記事で詳しく扱っているので、ここでは取得手順に絞ります。

1. 再現用のコード

import java.util.ArrayList;
import java.util.List;

public class OomDemo {
    // 注文データのキャッシュ（削除しないので増え続ける）
    static final List<byte[]> cache = new ArrayList<>();

    public static void main(String[] args) throws Exception {
        Runtime rt = Runtime.getRuntime();
        System.out.printf("maxMemory=%dMB%n", rt.maxMemory() / 1024 / 1024);
        for (int i = 1; ; i++) {
            cache.add(new byte[100 * 1024]); // 100KB ずつ追加
            if (i % 100 == 0) {
                System.out.printf("added=%dMB used=%dMB%n", i / 10,
                        (rt.totalMemory() - rt.freeMemory()) / 1024 / 1024);
            }
            Thread.sleep(1);
        }
    }
}

2. GC ログとヒープダンプを有効にして実行

javac OomDemo.java
mkdir -p dumps
java -Xms64m -Xmx64m \
  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=dumps/ \
  -Xlog:gc*:file=gc.log:time,uptime,level,tags:filecount=5,filesize=10m \
  -cp . OomDemo

maxMemory=64MB
added=10MB used=11MB
added=20MB used=21MB
added=30MB used=31MB
added=40MB used=41MB
added=50MB used=51MB
added=60MB used=61MB
java.lang.OutOfMemoryError: Java heap space
Dumping heap to dumps/java_pid12236.hprof ...
Heap dump file created [67147133 bytes in 0.032 secs]

Exception: java.lang.OutOfMemoryError thrown from the UncaughtExceptionHandler in thread "main"

$ ls -l dumps gc.log
-rw-r--r-- 1 root root 61193 Oct  2 05:00 gc.log
-rw------- 1 root root 67147133 Oct  2 05:00 java_pid12236.hprof

ヒープダンプは約64MBで、最大ヒープとほぼ同じ大きさになりました。ヒープダンプはヒープの中身をそのまま書き出すため、-Xmx8g なら最大で数GBのファイルになります。HeapDumpPath にはヒープサイズ以上の空きがある場所を指定してください。ファイル名は java_pid<PID>.hprof で、ディレクトリを指定するとその中に作られます。

3. GC ログを読む

gc.log から [gc ] タグの行（各 GC の要約）を抜き出した結果です。

[2026-10-02T05:00:38.767+0900][0.005s][info][gc     ] Using G1
[2026-10-02T05:00:38.904+0900][0.143s][info][gc          ] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 7M->6M(64M) 5.372ms
[2026-10-02T05:00:38.996+0900][0.234s][info][gc          ] GC(2) Pause Young (Normal) (G1 Evacuation Pause) 13M->13M(64M) 3.466ms
[2026-10-02T05:00:39.250+0900][0.488s][info][gc          ] GC(4) Pause Young (Normal) (G1 Evacuation Pause) 32M->32M(64M) 11.685ms
[2026-10-02T05:00:39.354+0900][0.592s][info][gc          ] GC(6) Concurrent Mark Cycle
[2026-10-02T05:00:39.431+0900][0.670s][info][gc          ] GC(7) Pause Young (Prepare Mixed) (G1 Evacuation Pause) 46M->46M(64M) 6.532ms
....
[2026-10-02T05:00:39.737+0900][0.976s][info][gc             ] GC(31) Pause Full (G1 Compaction Pause) 61M->61M(64M) 4.962ms
[2026-10-02T05:00:39.743+0900][0.981s][info][gc             ] GC(34) Pause Full (G1 Compaction Pause) 61M->61M(64M) 4.436ms
[2026-10-02T05:00:39.748+0900][0.986s][info][gc             ] GC(35) Pause Full (G1 Compaction Pause) 61M->61M(64M) 4.703ms

読むポイントは「GC 後の使用量が下がらないまま増え続けるか」と「Pause Full が連続していないか」です。このログでは -> の後ろが 6M→13M→32M→46M→61M と増え続け、最後は Full GC が 20 回出ても 61M のまま減らず、OutOfMemoryError になりました。これはメモリリーク（またはヒープ不足）の典型的な形です。

4. 実行中のプロセスからヒープダンプを取る（jcmd／jmap）

OOM を待たずに、動いているプロセスからダンプを取ることもできます。

jcmd <pid> GC.heap_dump /tmp/dumps/server.hprof
jmap -dump:live,format=b,file=/tmp/dumps/server-jmap.hprof <pid>
jcmd <pid> GC.class_histogram | head   # ダンプを取らずにクラス別の件数とサイズを見る

$ jcmd 13236 GC.heap_dump .../dumps/server.hprof
Dumping heap to .../dumps/server.hprof ...
Heap dump file created [6784640 bytes in 0.055 secs]

$ jcmd 13236 GC.class_histogram | head -6
 num     #instances         #bytes  class name (module)
-------------------------------------------------------
   1:         10945         754040  [B (java.base@21.0.10)
   2:            50         579360  [Ljava.util.concurrent.ConcurrentHashMap$Node; (java.base@21.0.10)
   3:          1699         336272  java.lang.Class (java.base@21.0.10)
   4:         10011         320352  java.lang.String (java.base@21.0.10)

取得した .hprof は Eclipse Memory Analyzer（MAT）や VisualVM で開き、どのオブジェクトがメモリを保持しているかを調べます。ヒープダンプには処理中のデータがそのまま含まれるため、保管場所と共有範囲には気を付けて扱いましょう。

OOM 時にすぐ終了させる（ExitOnOutOfMemoryError）

OOM が起きた JVM は、一部のスレッドだけが止まった中途半端な状態で動き続けることがあります。コンテナやサービス管理の仕組みで自動再起動できる環境なら、すぐに終了させる方が復旧が速くなります。

java -Xmx64m -XX:+ExitOnOutOfMemoryError -cp . OomDemo

added=60MB used=61MB
Terminating due to java.lang.OutOfMemoryError: Java heap space
$ echo $?
3

終了コード 3 で即座に終了しました。-XX:+HeapDumpOnOutOfMemoryError と組み合わせれば「ダンプを残してから終了」になります。終了ではなく JVM のクラッシュログ（hs_err ファイル）を残したい場合は -XX:+CrashOnOutOfMemoryError もあります。

JFR（Java Flight Recorder）で記録する

JFR は JVM に組み込まれた低負荷の記録機能で、GC・スレッド・CPU・メモリ割り当てなどのイベントをファイルに残せます。

java -XX:StartFlightRecording=duration=30s,filename=rec.jfr -jar app.jar
jcmd <pid> JFR.check                               # 記録中か確認
jcmd <pid> JFR.dump filename=now.jfr               # 途中経過を保存
jfr summary rec.jfr                                # 中身の概要
jfr print --events jdk.GCHeapSummary rec.jfr       # 特定イベントを表示

[1.578s][info][jfr,startup] Started recording 1. The result will be written to:
...
$ jcmd 13236 JFR.check
Recording 1: name=1 duration=30s (running)
$ ls -l rec.jfr
-rw-r--r-- 1 root root 237851 Oct  2 05:01 rec.jfr
$ jfr summary rec.jfr
 Version: 2.1
 Chunks: 1
 Start: 2026-10-01 20:01:18 (UTC)
 Duration: 30 s

30秒の記録で約232KBでした。記録ファイルは JDK Mission Control（JMC）で開くとグラフで確認できます。

デバッグ用オプション

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:7340 -cp . HeapInfo

Listening for transport dt_socket at address: 7340

address は 127.0.0.1:ポート のようにローカルに限定するのが基本です。*:ポート にすると外部から接続できる状態になります（なお今回の環境では *:7340 は IPv6 のソケットが作れず transport error 202 で起動しませんでした）。suspend=y にするとデバッガが接続するまで起動を待ちます。

コンテナで動かすときの設定

Java 10 以降（8u191 以降も）は、コンテナの CPU とメモリの上限を自動で認識します（-XX:+UseContainerSupport が既定で有効。Java 25 の公式ドキュメントでも同じ説明です）。実測のとおり、この環境ではコンテナ上限 5.84GB を基準に最大ヒープが決まりました。

# Dockerfile の例（イメージ名は利用している JDK/JRE イメージに合わせる）
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/dumps"

コンテナ実行（docker run -m 512m など）での確認は今回の環境では行っていません。上の実測はホスト自体のコンテナ上限（cgroup）と -XX:MaxRAM による疑似的な制限で確認したものです。

JAVA_TOOL_OPTIONS と JDK_JAVA_OPTIONS の違い

どちらも環境変数で JVM オプションを渡す方法ですが、読み取る対象と優先順位が違います。Java 21.0.10 で確かめた結果です。

javac やビルドツールにまで効いてほしくない設定（大きなヒープなど）は JDK_JAVA_OPTIONS、どの JVM でも効かせたいもの（証明書ストアやプロキシの設定など）は JAVA_TOOL_OPTIONSと使い分けると整理しやすくなります。Java 25 の公式ドキュメントでも「JDK_JAVA_OPTIONS の内容はコマンドラインから解析されたオプションの前に追加される」と説明されています。

Java 25 での主な違い（公式で確認）

手元には Java 21 しかないため、以下は OpenJDK の JEP と Java 25 の java コマンド公式ドキュメントで確認した内容です（未実行）。

Java 21 で -XX:+UseZGC -XX:+ZGenerational と書いた起動スクリプトは、Java 25 に上げるときに -XX:+ZGenerational を外すかどうかを公式リリースノートで確認してから移行してください。

よくある質問

Q. -Xms と -Xmx は同じ値にした方がよいですか？ A. サーバー用途では同じ値にすることが多いです。起動後のヒープ拡張・縮小がなくなり、動作が安定します。一方、メモリを他のプロセスと分け合う開発機やバッチでは、-Xms を小さくして使った分だけ確保する方が効率的です。

Q. コンテナでは -Xmx と MaxRAMPercentage のどちらを使えばよいですか？ A. MaxRAMPercentage がおすすめです。コンテナのメモリ上限を変えたときに自動でヒープも追従します。両方書くと -Xmx が優先されるので、どちらか一方にそろえてください。

Q. GC ログは本番で常に出してよいですか？ A. -Xlog:gc* をファイルに出す程度なら負荷は小さく、常に有効にしておく運用が一般的です。filecount と filesize でローテーションを設定し、ディスクを使い切らないようにします。

Q. 今の JVM にどのオプションが効いているか確認するには？ A. 起動前なら java <オプション> -XX:+PrintFlagsFinal -version、起動後なら jcmd <pid> VM.flags や jcmd <pid> VM.command_line で確認できます。末尾の {ergonomic} は JVM が自動で決めた値です。

まとめ

• 最大ヒープの既定はメモリ（コンテナなら上限）の25%。この環境では 5.84GB の25%で約1496MB だった
• -Xmx と MaxRAMPercentage を両方書くと -Xmx が優先。コンテナでは MaxRAMPercentage が扱いやすい
• 1 CPU だと GC は Serial が自動選択される。既定の G1 を前提にするなら CPU 数も確認する
• GC ログは -Xlog:gc*:file=...:time,uptime,level,tags:filecount=5,filesize=10m。Java 8 の PrintGCDateStamps などは Java 21 では起動しない
• -XX:+HeapDumpOnOutOfMemoryError でダンプは最大ヒープ程度の大きさ（64MB ヒープで約64MB）。出力先の空きを確保する
• JAVA_TOOL_OPTIONS は全 JVM、JDK_JAVA_OPTIONS は java コマンドだけ。優先順位はコマンドライン＞JDK_JAVA_OPTIONS＞JAVA_TOOL_OPTIONS
• Java 25 では ZGC が世代別のみになり、-XX:+ZGenerational は不要

株式会社RJCでは、JVMオプションの読み方や設定の考え方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。