HeapLens — Java & Android Heap Dump Analyzer

Investigate heap dumps locally with a shared Rust engine and editor-native views.

Why HeapLens?

HeapLens brings Java and Android heap dump analysis into VS Code, with an IntelliJ adapter and standalone CLI/browser interfaces built on the same Rust engine. Open a supported .hprof file to investigate dominator trees, class histograms, leak suspects, estimated waste and other analysis views. Heap analysis runs locally; optional AI and telemetry have separate data-sharing controls.

HeapLens includes a built-in AI assistant that explains heap analysis findings in plain English and suggests code-level fixes. Ask questions like "Why is my app using 2 GB of memory?" or "What's causing this OutOfMemoryError?" and get actionable answers powered by your choice of 10 LLM providers including local models via Ollama.

The native engine maps the capture read-only and uses compact CSR reference graphs. HeapQL provides SQL-like queries over objects, class aggregates and ownership. Analysis time and memory depend on object/edge density, storage and cache state, not just dump size. Start with the host and installation guides for package availability and platform requirements.

Analysis modes

• Full analysis is the default. The editor displays progress immediately, then shallow Overview/Histogram results when available, while references and dominators continue. Retained results appear only after they are computed.
• Quick Scan returns allocation counts and shallow sizes without a reference graph. Choose Analyze Retained when you need ownership, paths, queries and other graph-dependent actions. Quick Scan supports conventional HPROF 1.0.1 and 1.0.2.
• Memory storage is the default and rebuilds the graph for each new analysis. Disk-backed references build a private reusable index; reopening verifies the capture/index and recomputes dominators. Disk mode can reduce allocated working memory but can be slower on a first build and still needs RAM and free disk space.
• Waste is on demand. Choose Calculate Waste, or use heaplens analyze app.hprof --with-waste. An uncalculated result is not zero waste.

See storage and resource guidance. Completed disk indexes persist after closing the dump, contain sensitive metadata and are not encrypted or automatically uploaded.

Features

11 Interactive Tabs

Dominator Tree Actions

Every node in the dominator tree has one-click actions:

• Why alive? — shows the shortest GC root path as a breadcrumb
• Inspect — opens a field-level inspector panel with primitive values and reference links
• Go to source — jumps to the .java file (workspace, dependency JAR, or decompiled)
• Show referrers — "Who references this object?" with recursive drill-down

HeapQL Query Language

A SQL-like language purpose-built for heap analysis:

-- Find all HashMaps retaining more than 1MB
SELECT * FROM instances
WHERE class_name = 'java.util.HashMap' AND retained_size > 1MB
ORDER BY retained_size DESC

-- Top 10 classes by total retained size (with column aliases)
SELECT class_name, COUNT(*) AS instance_count, SUM(retained_size) AS total_retained
FROM class_histogram
GROUP BY class_name
ORDER BY total_retained DESC LIMIT 10

-- JOIN instances with class histogram
SELECT * FROM instances i
JOIN class_histogram c ON class_name = class_name
WHERE i.retained_size > 1MB LIMIT 10

-- Subquery: objects larger than average
SELECT * FROM instances
WHERE retained_size > (SELECT AVG(retained_size) FROM instances)
ORDER BY retained_size DESC LIMIT 10

-- GC root path for a specific object
:path 123456789

-- Who references this object?
:refs 123456789

• Tables: instances, class_histogram, dominator_tree, leak_suspects
• JOINs: INNER JOIN, LEFT JOIN with table aliases
• Aggregates: COUNT, SUM, AVG, MIN, MAX with AS aliases
• Subqueries: WHERE col IN (SELECT ...), WHERE col > (SELECT AVG(...) FROM ...)
• Size literals: 1KB, 5MB, 1GB

AI-Powered Analysis

Configure any of the 10 supported LLM providers and ask questions in the AI Chat tab. Supports Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, Groq, xAI (Grok), Together AI, OpenRouter, and Ollama (local):

"What's causing the high memory usage?" "Show me the top 10 classes by retained size" "Why is this HashMap so large?"

The LLM responds with explanations and runnable HeapQL queries. Click Run Query to execute them inline.

Privacy: AI Chat, Explain and Copilot context send heap metadata, not the dump file. Automatic duplicate-string contents and primitive field values are omitted; class/field names and messages you type are not anonymized. Fix with AI asks before each full-source submission and shows the destination. Cancel or Review Source sends nothing; the prompt does not add the local file path. Approved source can still contain secrets or paths. Ollama is local only when the configured endpoint and its model processing are local. MCP tools have a separate data-sharing boundary; see the privacy details.

Instance Enumeration

After full analysis, click a class name in Histogram to browse its instances. Each instance row has actions for inspection, referrers and "Why alive?". Quick Scan provides the shallow class table without an object-instance index.

Source Code Bridge

Three-tier source resolution:

1. Workspace — finds .java files in your project
2. Dependencies — extracts from Maven/Gradle source JARs (~/.m2, ~/.gradle)
3. Decompilation — falls back to CFR decompiler when source JARs are unavailable

Waste Detection

Choose Calculate Waste after full analysis to estimate these patterns:

• Duplicate strings — identical string values held multiple times
• Empty collections — HashMap, ArrayList, etc. with zero elements
• Over-allocated collections — arrays sized far beyond their element count
• Boxed primitives — Integer, Long, etc. that could be primitive

Snapshot Comparison & Timeline

• Compare two heap dumps: summary delta, class-level growth/shrinkage with change badges, leak suspect changes (new/resolved/persisted), and a D3.js bar chart of top changes. Waste deltas require calculated Waste in both interactive snapshots.
• Copy Report copies a full markdown diff report to clipboard.
• Export CSV saves all class changes to a file.
• Timeline multiple snapshots: track heap growth trends over time with interactive charts.

Getting Started

1. Install HeapLens from the VS Code Marketplace
2. Open a completed supported .hprof file — HeapLens activates automatically and shows analysis progress.
3. Explore Overview and Histogram as their results become available; use Dominator Tree and the other graph-dependent actions after full analysis completes.
4. Choose storage with HeapLens: Configure Analysis Storage. Close and reopen the dump after a change. Select HeapLens: Analysis Initial Mode → shallow in Settings when you want Quick Scan first.

Generate a Heap Dump

# From a running JVM
jmap -dump:format=b,file=heap.hprof <pid>

# On OutOfMemoryError (add to JVM args)
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./heap.hprof

# Android (via adb)
adb shell am dumpheap <pid> /data/local/tmp/heap.hprof
adb pull /data/local/tmp/heap.hprof

AI Chat Setup (Optional)

1. Go to Settings > search heaplens.llm
2. Set heaplens.llm.provider to your preferred provider (Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Groq, xAI, Together AI, OpenRouter, or Ollama)
3. Run HeapLens: Set or Replace LLM API Key from the Command Palette (not needed for Ollama). The eye button can temporarily reveal what you are typing. HeapLens stores one encrypted key per provider using the editor's VS Code SecretStorage implementation.
4. Open the AI Chat tab and start asking questions

To verify a saved credential without exposing it, run HeapLens: Show LLM API Key Status. HeapLens shows only a fixed mask and, for keys longer than four characters, the final four characters. Saved keys cannot be revealed in full; replace the key if it is uncertain.

Settings

Architecture

• Shared Rust engine — mapped HPROF input, compact CSR storage, dominator analysis, HeapQL and on-demand Waste. Optional versioned structural indexes use bounded writing, mapped catalogs and selective lossless encoding.
• Host adapters — VS Code custom editor, IntelliJ plugin, and standalone CLI/browser. Credentials, source navigation, consent and process lifecycle remain host-specific.
• MCP server — updated local builds require --mcp, exact-file --mcp-allow-file approvals and --mcp-share-metadata; six bounded metadata tools with no raw-value or unrestricted-query fallback. See setup.

See the animated architecture and data-flow diagrams.

Supported Formats

• Java HotSpot HPROF (JDK 8+) — analyze heap dumps from any JVM application, Spring Boot, microservices, or Kubernetes pods
• Android HPROF (Dalvik/ART) — debug memory leaks in Android apps directly from adb heap dumps
• HPROF versions: 1.0.1, 1.0.2, 1.0.3
• Works with heap dumps generated by jmap, jcmd, -XX:+HeapDumpOnOutOfMemoryError, and Android Debug Bridge

Commands

Requirements

• VS Code 1.74.0 or later
• No additional dependencies — the native Rust binary is bundled with the extension

Optional:

• Java on PATH (for CFR decompilation fallback)
• Maven/Gradle project (for dependency source resolution)
• API key for AI Chat (Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Groq, xAI, Together AI, OpenRouter, or use Ollama for free local models)

Performance

The following previously recorded figures describe selected captures on an Apple M2 Max (originally reported as the median of five runs). They are not fresh measurements of this release, cold-start guarantees or predictions for other captures:

Object count, reference density and page-cache state can change both time and RAM substantially. Compare Memory first analysis, Disk first build and Disk reopening separately, and include Waste consistently. See recorded measurements and their scope.

Telemetry

VS Code and standalone CLI/browser telemetry default to usage and errors (all), subject to the applicable host controls. IntelliJ telemetry is off until explicit approval: the first HeapLens editor asks whether to enable Errors Only or Usage and Errors. No telemetry is collected or sent beforehand. Cancel, dismissal or No Telemetry keeps it off; the choice persists locally. Earlier prototype On settings require fresh approval. Development/CI reporting and DO_NOT_TRACK=1 remain disabled.

Errors-only collection is available with error instead of all. For a first run without reporting on any host, set DO_NOT_TRACK=1 before starting the IDE or CLI. IntelliJ already starts off pending permission. On other hosts set Off before opening a dump; disabling later cannot recall events already transmitted.

Telemetry sends allowlisted codes, actions, coarse platform/version information and rounded counts, sizes or timings to HeapLens Azure Application Insights. In the updated VS Code implementation, permitted usage events also include Microsoft's SDK identifiers supplied by VS Code (machineId and sessionId) for reporting-machine/session counts. These are pseudonymous identifiers, not names or verified people. Errors Only excludes usage and counting IDs. IntelliJ and standalone telemetry remain identity-free and retain their existing controls. No host sends raw error messages/stacks, paths, dump values, class names, source, queries or credentials through routine telemetry. Recent filtered diagnostics can be reviewed locally; the review describes SDK enrichment but does not expose IDs or upload the report. Network services can process IP addresses. AI submissions and user-selected exports have separate sharing rules. See telemetry fields, controls and limitations.

License

Apache 2.0