Documentation

Introduction

JVMind is an AI-powered conversational assistant for Java Virtual Machine (JVM) performance troubleshooting. Upload your GC logs or thread dumps, ask questions in natural language, and get professional diagnostic reports with actionable recommendations.

Instead of manually parsing thousands of log lines or hunting for deadlocks in a massive thread dump, just upload your file and let the AI do the heavy lifting — it will analyze the data step-by-step and explain what's happening in plain English.

Key Features

GC Log Analysis

How to Generate GC Logs

Before uploading, make sure your JVM is configured to output GC logs:

How to Analyze

1. Start a new conversation, or switch to an existing one
2. Click the Analysis button on the top bar to open the analysis panel
3. In the GC tab, drag & drop your GC log file, or click to select it
4. Wait for the analysis to complete — you'll see statistics and charts appear
5. In the chat, ask the AI to diagnose: "Please analyze this GC log and give me optimization suggestions"

What Gets Analyzed

• Collector Identification — automatically detects G1, Parallel, Serial, Shenandoah, or ZGC
• Heap Summary — min, max, and average heap usage
• GC Statistics — counts by category (Young, Mixed, Full)
• Throughput — percentage of time the application spends running vs GC pausing
• Pause Time Analysis — total, average, P95, P99 percentiles
• Top 10 Slowest — GC events with the longest pauses
• Full GC by Cause — breakdown of what triggered each Full GC
• Charts — heap usage timeline, pause time distribution histogram

Tip: For the best AI diagnosis, upload the GC log first, then ask questions in the chat. The AI will automatically reference the already-uploaded analysis data.

Example Questions to Ask

• "What's the throughput? Is that healthy?"
• "Why are there so many Full GCs?"
• "Check if this looks like a memory leak"
• "What should I adjust to reduce Young GC pause time?"

Diagnostic Rules

JVMind's GC analysis is built on a library of 14 expert rules that detect specific symptoms and assign a severity. Each report is then summarized into a single root cause with two layers of supporting findings: direct evidence and downstream symptoms. This section documents the rules so you know what each detection means and when to take action.

Rules are grouped by which garbage collector they apply to. Universal rules run for every collector. Collector-specific rules only fire when the log is recognized as that collector.

Root Cause Categories

Every report produces exactly one root cause:

Health Banner Levels

The colored banner at the top of every report is derived from the root cause category and the severity of active findings. The vocabulary is consistent with the diagnosis below — banner never says "critical" while the diagnosis says "performance issue".

Universal Rules

Apply to every collector. Each rule fires independently based on aggregate statistics.

G1-Specific Rules

Fire only when the collector is identified as G1.

CMS-Specific Rules

Fire only when the collector is identified as CMS.

ZGC-Specific Rules

Fire only when the collector is identified as ZGC.

Key Design Principles

• OOM = Full GC + cannot reclaim. A single Full GC with normal reclaim ratio is performance, not OOM. Only when Full GC is combined with reclaim_low (avg reclaim < 5%) does the diagnosis escalate to OOM root cause. This avoids false alarms from System.gc() or one-off heap dumps.
• Manual triggers are not heap pressure. When the cause is Heap Dump Initiated GC (jmap -dump / jcmd GC.heap_dump) or Heap Inspection (jcmd inspection), the rule fires as intentional, not heap pressure, severity is capped at medium, and the detail text says so explicitly.
• System.gc() is application code, not heap pressure. Full GC with cause System.gc(), Heap Dump Initiated GC, or Heap Inspection are treated as manual triggers and excluded from gc_frequency_high. Production should consider -XX:+DisableExplicitGC to disable, unless required by libraries (RMI, JMX, etc.). The dedicated explicit_gc_called rule fires at medium (1-2 occurrences) or high (≥ 3) severity with a direct recommendation to investigate the calling code — even when the underlying collector (ZGC, G1, Parallel, ...) is otherwise healthy.
• G1 mixed-manual detection. When a log has both manual triggers (e.g. System.gc()) and real heap-pressure Full GC (e.g. G1 Compaction Pause), g1_full_gc produces a dedicated "mixed" detail that breaks down both counts separately — so the user understands the diagnosis correctly instead of seeing all Full GC attributed to "heap pressure".
• CMS rules → performance by default. CMS is designed to allow Full GC fallback. cms_concurrent_mode_failure and cms_promotion_failed alone are categorized as performance; they only escalate to OOM when paired with reclaim_low.
• ZGC hard fallback → OOM category. ZGC doesn't produce traditional Full GC. Its equivalent hard fallbacks — zgc_allocation_stall (sync mode) and zgc_concurrent_cycle_failure — are categorized as performance by default; they only escalate to OOM when paired with reclaim_low (heap actually cannot reclaim). This matches the same "OOM = cannot reclaim" principle applied to G1, and avoids false-positive OOM alerts when ZGC is operating normally under high allocation rate.
• Evidence vs Symptoms. Findings are split into two layers based on the active root cause: evidence findings directly support the root cause; symptoms findings are downstream effects. This avoids the confusing flat-list view where unrelated findings mix together.

Tip: Every report has a collapsible Rules Reference panel below the diagnosis listing all 14 rules with thresholds, so you don't need to leave the app to look them up.

Thread Dump Analysis

How to Capture a Thread Dump

Use the jstack command for classic text format (all JDK versions):

jstack -l <pid> > threads.txt

Or use jcmd for the JSON format (JDK 21+, includes virtual thread metadata):

jcmd <pid> Thread.dump_to_file -format=json threads.json

Or capture directly in JVMind using the jstack tab's built-in capture tool (requires the agent to be running on your JVM host).

How to Analyze

1. Open the analysis panel ( button on the top bar)
2. Select the jstack tab
3. Upload your thread dump file
4. Ask the AI to diagnose: "Find any deadlocks or lock contention in this thread dump"

What Gets Analyzed

• Thread State Distribution — counts of RUNNABLE, BLOCKED, WAITING, TIMED_WAITING threads
• Deadlock Detection — automatically finds circular deadlocks and displays the full wait chain
• Lock Contention — identifies which locks cause the most blocking
• Thread Grouping — groups threads by name prefix (e.g., Tomcat worker threads, GC threads)
• CPU Hotspot Detection — which methods appear most frequently on RUNNABLE threads
• Flame Graph — interactive flame graph of all stack traces
• Virtual Threads (JSON only) — count of virtual threads, TERMINATED threads, and thread-container distribution (ForkJoinPool.commonPool, ThreadPerTaskExecutor, …). Unnamed virtual threads are synthesized as VThread-<container>#<tid> for grouping.

Example Questions to Ask

• "Is there a deadlock? Show me the full chain"
• "Why is CPU so high? Which threads are running?"
• "Check for any threads blocked on the same lock"
• "Help me understand this flame graph — what should I optimize?"

Configuration

LLM Settings

Click the button in the sidebar to open the configuration dialog:

After saving, click "Test Connection" to verify your settings work before starting a conversation.

Supported Providers

JVMind includes presets for popular LLM providers:

• OpenAI — GPT-4o, GPT-4o-mini
• DeepSeek — deepseek-chat, deepseek-coder
• Alibaba Cloud — Qwen (通义千问)
• Moonshot — Kimi

Conversation Guide

How the AI Thinks

JVMind uses the ReAct (Reasoning + Acting) framework. When you ask a question, the AI:

1. Thinks about what information it needs
2. Calls a tool (e.g., analyzes GC log, reads a report, calculates something)
3. Observes the result
4. Repeats until it has enough context to give a complete answer

The entire thought process is visible in the conversation — you can see exactly how the AI reached its conclusions.

Tips for Better Answers

• Be specific — "Check if the Full GC pause time is causing latency issues" is better than "Is GC OK?"
• Upload first, ask second — upload your GC log or jstack file before asking about it
• One topic at a time — focus on one issue per message for clearer analysis
• Use the memory feature — add facts about your application in the sidebar memory panel so the AI remembers them across conversations

Memory

The sidebar Memory panel lets you save facts the AI should remember, such as:

• Your JVM version and heap size
• Your application's traffic patterns
• Previous optimization attempts and their results

The AI automatically references saved facts in future conversations for more contextual answers.

Supported Formats

GC Collectors

Thread Dump Formats

JVMind supports two thread dump formats, auto-detected on upload:

• Text (jstack -l) — the classic format, works on all JDK versions. Extensions: .txt, .log, .tdump, .jstack.
• JSON (jcmd Thread.dump_to_file -format=json) — introduced in JDK 21, the only way to see virtual thread details (JEP 444). Extension: .json. Adds statistics for virtual threads, terminated threads, and thread containers (executor / ForkJoinPool grouping).

Files must be UTF-8 encoded (or plain ASCII).

ZGC Specifics

JVMind correctly handles ZGC's multi-phase pause structure by accumulating pause times from all phases of the same GC cycle. It also recognizes both the older Garbage Collection (System.gc()) format and the JDK 25+ Major Collection (System.gc()) format for detecting explicit Full GC triggered by System.gc().

Frequently Asked Questions

Q: Is my data sent to the AI provider?

The analysis results (statistics, not the raw file) are sent to the LLM you configured for diagnosis. The raw file stays on the JVMind server.

Q: Does it work with application servers like Tomcat or Jetty?

Yes — JVMind works with any Java application regardless of the application server or framework. It only needs the GC log or thread dump.

Q: What about very large log files?

File size limits: Loading.... Your current plan's limit is shown in the app sidebar.

Q: How accurate is the AI diagnosis?

The AI provides professional-level analysis comparable to an experienced performance engineer. However, always verify critical recommendations before applying them to production, especially if your log doesn't contain full context.

Q: Can I analyze multiple files at once?

You can upload multiple GC log files or thread dumps to a single conversation. Each will appear in the analysis panel's history, and the AI can compare them.

Q: Does JVMind work with rotating GC logs?

Yes — upload them individually or concatenate them into one file before uploading.

Q: Where can I learn what each diagnostic rule means?

See the Diagnostic Rules section above — it documents all 14 rules, their thresholds, and the root cause categories.