Skip to content

headless_and_programmatic

Jump to bottom
Jason Koch edited this page Mar 2, 2026 · 1 revision

Headless and Programmatic Usage

Eclipse Memory Analyzer is an Eclipse application. Its parsers, queries, and extension points are all wired through the Eclipse OSGi plugin infrastructure. This means you cannot simply add MAT JARs to a plain Java classpath and call SnapshotFactory.openSnapshot() -- the Eclipse extension registry will not be initialized, and you will get a NullPointerException from Platform.getExtensionRegistry().

There are several supported ways to use the MAT analysis engine without the desktop GUI, ranging from simple command-line scripts to full programmatic embedding.

Approach comparison

Approach Effort Best for
ParseHeapDump scripts Low -- run a shell script CI pipelines, batch reports, one-off server-side analysis
Eclipse JIFA Medium -- deploy a service or container Web-based collaborative analysis, REST API access to MAT
Direct OSGi embedding High -- bootstrap Equinox yourself Custom tooling that needs full ISnapshot API access
Docker wrapping Low -- pull an image Portable CI/CD without installing MAT

ParseHeapDump scripts

Every MAT installation includes ParseHeapDump.sh (Linux/macOS) and ParseHeapDump.bat (Windows). These scripts launch the MAT engine as an Eclipse headless application and produce ZIP files containing HTML reports.

Basic indexing

Running without any report arguments parses the heap dump and generates index files. These index files make subsequent analysis (in the GUI or via further script runs) significantly faster.

/path/to/mat/ParseHeapDump.sh /path/to/heapdump.hprof

Generating reports

Append one or more report IDs to produce ZIP files with HTML reports:

/path/to/mat/ParseHeapDump.sh /path/to/heapdump.hprof \
  org.eclipse.mat.api:suspects \
  org.eclipse.mat.api:overview \
  org.eclipse.mat.api:top_components

Available built-in reports:

Report ID Output
org.eclipse.mat.api:suspects Leak suspect report
org.eclipse.mat.api:overview Overview report
org.eclipse.mat.api:top_components Top memory consumers by component

Running a single query

The org.eclipse.mat.api:query report runs a single MAT command or OQL query and produces an HTML report from the result.

# Run the histogram command
/path/to/mat/ParseHeapDump.sh heapdump.hprof \
  "-command=histogram" \
  org.eclipse.mat.api:query

# Run an OQL query (quote the whole -command argument)
/path/to/mat/ParseHeapDump.sh heapdump.hprof \
  "-command=oql \"SELECT * FROM java.lang.String s WHERE s.count > 1000\"" \
  org.eclipse.mat.api:query

Add -format=txt -unzip after the report ID to get plain text output instead of zipped HTML.

Comparing two heap dumps

# General comparison
/path/to/mat/ParseHeapDump.sh heapdump1.hprof \
  -snapshot2=heapdump2.hprof \
  org.eclipse.mat.api:compare

# Leak suspects comparison
/path/to/mat/ParseHeapDump.sh heapdump1.hprof \
  -baseline=heapdump2.hprof \
  org.eclipse.mat.api:suspects2

Parse options

Option Effect
-keep_unreachable_objects Retain objects not reachable from GC roots
-snapshot_identifier=<id> Select a specific snapshot when the file contains multiple (e.g. #1, #2)
-discard_pattern=<regex> (Experimental) Discard objects matching the class name pattern

Truly headless environments (no GTK)

Newer versions of ParseHeapDump.sh invoke the MemoryAnalyzer binary, which may attempt to load GTK libraries. On servers without a display or GTK, invoke the Equinox launcher directly:

java -Xmx4g \
  -jar /path/to/mat/plugins/org.eclipse.equinox.launcher_*.jar \
  -consoleLog \
  -application org.eclipse.mat.api.parse \
  /path/to/heapdump.hprof \
  org.eclipse.mat.api:suspects

Adjust -Xmx to match the size of the heap dump being analyzed. See the FAQ for sizing guidance.

Batch mode reference

See the Eclipse help page on Batch mode for the full reference.

Eclipse JIFA

Eclipse JIFA (Java Issue Finding Assistant) wraps the MAT analysis engine in a web application with a REST API. It handles the OSGi bootstrapping internally, so you do not need to manage Eclipse infrastructure yourself.

JIFA provides:

  • A web UI for heap dump analysis (leak detection, dominator tree, OQL)
  • GC log, thread dump, and JFR analysis
  • Collaborative analysis -- multiple users can access the same server

Quick start with Docker

docker run -p 8102:8102 eclipsejifa/jifa

The service is then available at http://localhost:8102. Upload a heap dump through the web interface to begin analysis.

To analyze a local file directly:

docker run -p 8102:8102 \
  -v /path/to/dumps:/dumps \
  eclipsejifa/jifa

Building from source

git clone https://github.com/eclipse/jifa.git
cd jifa
./gradlew buildJifa

JIFA's Gradle build uses the p2asmaven plugin to download MAT JARs from the Eclipse P2 update sites automatically.

When to use JIFA

JIFA is the recommended path when you want to use the MAT engine from a non-Eclipse Java application. Rather than bootstrapping OSGi yourself, JIFA provides a tested integration. It is also useful when you need to share analysis results across a team via a central server.

For more information, see the JIFA documentation.

Direct OSGi embedding

If you need full programmatic access to the MAT ISnapshot API within your own JVM process, you must bootstrap the Eclipse Equinox OSGi runtime so that MAT's extension points are properly initialized.

This is an advanced approach. The MAT codebase does not provide a standalone "MAT as a library" artifact -- the Eclipse plugin architecture is a fundamental part of the design, not an incidental dependency.

Reference implementations

Two existing implementations demonstrate the pattern:

  1. ParseSnapshotApp in the MAT source code (ParseSnapshotApp.java) is the application behind ParseHeapDump.sh. It shows how to open a snapshot and run queries within a properly initialized Eclipse application.

  2. Eclipse JIFA embeds the MAT engine by pulling dependencies from Eclipse P2 update sites and initializing the OSGi bundle context. Its HeapDumpAnalyzerImpl class demonstrates calling SnapshotFactory with a properly running extension registry.

Key requirements

  • All MAT plugins and their transitive Eclipse dependencies must be available as OSGi bundles
  • The Equinox OSGi framework must be started before any MAT API calls
  • Extension points for parsers (HPROF, DTFJ) and queries are discovered through the Eclipse extension registry at runtime

Common pitfall

Calling SnapshotFactory.openSnapshot() without a running OSGi runtime produces:

java.lang.NullPointerException: Cannot invoke
  "org.eclipse.core.runtime.IExtensionRegistry.getExtensionPoint(String)"
  because the return value of
  "org.eclipse.core.runtime.Platform.getExtensionRegistry()" is null

This error means the Eclipse platform is not initialized. You must either use one of the higher-level approaches above (ParseHeapDump, JIFA) or fully bootstrap Equinox in your application.

See issue #155 for further discussion of this topic.

Docker wrapping

For CI/CD pipelines where you want MAT analysis without installing it on the build agent, a Docker image can be used.

The dgroup/mat project provides a pre-built Docker image:

docker run -it --rm \
  -v "$PWD":/dumps -w /dumps \
  dgroup/mat \
  /mat/ParseHeapDump.sh heapdump.hprof \
    org.eclipse.mat.api:suspects \
    org.eclipse.mat.api:overview \
    org.eclipse.mat.api:top_components

This approach combines the simplicity of the ParseHeapDump scripts with the portability of containers.

Clone this wiki locally