Eclipse Mat

MAT Heap Dump Analysis

Analyze Java heap dumps headlessly using Eclipse MAT via the scripts/mat.sh shell wrapper.

Prerequisites

• MAT installed at /Applications/MemoryAnalyzer.app/Contents/Eclipse/ (new) or /Applications/mat.app/Contents/Eclipse/ (legacy), auto-detected in that order (or set MAT_HOME)
• Java 17+ available via $JAVA_HOME/bin/java, /usr/libexec/java_home -V, or java on PATH

Script Location

scripts/mat.sh in this skills folder.

Environment Variables

Operations

1. Healthcheck — Verify MAT + Java setup

scripts/mat.sh healthcheck

Run this first to confirm MAT and Java are available.

2. Index Status — Check if a heap dump is already indexed

scripts/mat.sh index-status /path/to/dump.hprof

If the heap dump has been parsed before, MAT creates .index files next to it. This avoids re-indexing on subsequent operations.

3. Parse Report — Run predefined analysis reports

scripts/mat.sh report /path/to/dump.hprof <report_id> [options...]

Available report IDs:

Examples:

# Leak suspects
scripts/mat.sh report dump.hprof org.eclipse.mat.api:suspects

# Overview
scripts/mat.sh report dump.hprof org.eclipse.mat.api:overview

# Comparison (two heap dumps)
scripts/mat.sh report dump.hprof org.eclipse.mat.api:compare -baseline baseline.hprof

Reports generate HTML/ZIP artifacts in the same directory as the heap dump.

4. OQL Query — Execute Object Query Language queries

scripts/mat.sh oql /path/to/dump.hprof "<query>" [--format txt|html|csv] [--limit N]

Examples:

# List all String objects
scripts/mat.sh oql dump.hprof "SELECT * FROM java.lang.String" --limit 100

# Inspect fields of a specific object by address
scripts/mat.sh oql dump.hprof "SELECT p.topic FROM OBJECTS 0x12345678 p"

# Find instances of a class
scripts/mat.sh oql dump.hprof "SELECT p FROM INSTANCEOF com.example.MyClass p" --limit 50

5. Run Command — Execute built-in MAT analysis commands

scripts/mat.sh command /path/to/dump.hprof <command_name> [args] [--format txt|html|csv] [--limit N]

Examples:

# Class histogram
scripts/mat.sh command dump.hprof histogram

# Dominator tree
scripts/mat.sh command dump.hprof dominator_tree

# Path to GC roots for a specific object
scripts/mat.sh command dump.hprof path2gc 0x12345678

# Thread overview
scripts/mat.sh command dump.hprof thread_overview

# Find strings
scripts/mat.sh command dump.hprof find_strings --limit 200

Supported Commands (56 total)

See references/commands.md for the full list with descriptions.

OQL Specification

MAT uses its own OQL dialect in "parse-application command mode":

Command format: -command=oql "<query>"

Supported Patterns

Known Limitations

• SQL-like GROUP BY / ORDER BY frequently fail in parse-app query mode
• Dialect-specific helpers like classof(...) may be rejected depending on parser context
• For ranking/top classes, prefer MAT overview/suspects reports then parse the artifacts
• For root-cause inspection, use targeted field-level OQL against object addresses

Instructions for Heap Dump Analysis

Recommended Workflow

1. Healthcheck first: Run scripts/mat.sh healthcheck to verify the setup
2. Check index status: Run scripts/mat.sh index-status <heap> — if already indexed, subsequent operations will be faster
3. Start with overview: Run scripts/mat.sh report <heap> org.eclipse.mat.api:overview to get class histogram and system info
4. Run leak suspects: Run scripts/mat.sh report <heap> org.eclipse.mat.api:suspects for automatic leak detection
5. Drill down: Use scripts/mat.sh command <heap> histogram for class-level breakdown, then dominator_tree for retained size analysis
6. Investigate specific objects: Use scripts/mat.sh oql <heap> "SELECT ..." to inspect individual objects by address or class
7. Thread analysis: Use scripts/mat.sh command <heap> thread_overview to see thread stacks and local variables

Reading Results

• Reports generate HTML directories and ZIP files next to the heap dump (e.g., dump_Leak_Suspects/)
• Queries and commands produce text results in *_Query/pages/Query_Command*.txt
• The script automatically displays text results and lists generated artifacts
• For HTML reports, read the generated files in the report directory

Tips

• First-time analysis of a heap dump triggers indexing, which can take minutes for large dumps. Subsequent operations reuse the index.
• Increase MAT_XMX for very large heap dumps (e.g., MAT_XMX=8g)
• Increase MAT_TIMEOUT for long-running analyses (e.g., MAT_TIMEOUT=3600)
• Use --limit with OQL and commands to avoid overwhelming output
• The path2gc command is invaluable for understanding why objects are retained
• Compare two heap dumps with org.eclipse.mat.api:compare to find growth patterns