{"id":46654649,"url":"https://github.com/sachinkg12/heaplens","last_synced_at":"2026-04-01T19:01:05.174Z","repository":{"id":342944318,"uuid":"1133285320","full_name":"sachinkg12/heaplens","owner":"sachinkg12","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-28T04:49:54.000Z","size":71621,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T09:37:48.015Z","etag":null,"topics":["android","developer-tools","heap-dump","java","jvm","memory-analysis","memory-leak","profiling","rust","vscode-extension"],"latest_commit_sha":null,"homepage":"https://sachinkg12.github.io/heaplens/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sachinkg12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-13T06:17:55.000Z","updated_at":"2026-03-28T07:07:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sachinkg12/heaplens","commit_stats":null,"previous_names":["sachinkg12/heaplens"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/sachinkg12/heaplens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sachinkg12%2Fheaplens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sachinkg12%2Fheaplens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sachinkg12%2Fheaplens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sachinkg12%2Fheaplens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sachinkg12","download_url":"https://codeload.github.com/sachinkg12/heaplens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sachinkg12%2Fheaplens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","developer-tools","heap-dump","java","jvm","memory-analysis","memory-leak","profiling","rust","vscode-extension"],"created_at":"2026-03-08T07:13:25.726Z","updated_at":"2026-04-01T19:01:05.165Z","avatar_url":"https://github.com/sachinkg12.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HeapLens — Java \u0026 Android Heap Dump Analyzer\n\n**The fastest way to understand Java heap dumps — right inside VS Code.**\n\n[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/guptasachinn.heaplens)](https://marketplace.visualstudio.com/items?itemName=guptasachinn.heaplens)\n[![Installs](https://img.shields.io/visual-studio-marketplace/i/guptasachinn.heaplens)](https://marketplace.visualstudio.com/items?itemName=guptasachinn.heaplens)\n[![License](https://img.shields.io/github/license/sachinkg12/heaplens)](LICENSE)\n[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19121302-blue)](https://doi.org/10.5281/zenodo.19121302)\n\n![HeapLens Demo](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/demo.gif)\n![HeapLens Overview](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/overview.png)\n\n---\n\n## Why HeapLens?\n\nHeapLens brings Java and Android heap dump analysis into VS Code. Open any `.hprof` file and instantly explore memory usage through 10 interactive views — dominator trees, class histograms, leak suspects, waste detection, and more. No separate tools. No context switching. No uploading to cloud services.\n\nHeapLens 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.\n\nBuilt on a native Rust engine using zero-copy mmap parsing with a two-phase CSR architecture, HeapLens handles production-sized heap dumps with ease. A 2 GB heap dump analyzes in about 1 second; a 14 GB dump completes in under 11 seconds on an M1 Mac. HeapLens also introduces HeapQL, a SQL-like query language purpose-built for heap analysis — query any object, filter by retained size, join across tables, and export results, all without leaving your editor.\n\n---\n\n## Features\n\n### 10 Interactive Tabs\n\n| Tab | What it does |\n|-----|-------------|\n| **Overview** | Heap stats, top objects, D3.js pie \u0026 bar charts |\n| **Histogram** | Sortable class table with instance counts and sizes — click a class to list all instances |\n| **Dominator Tree** | Expandable lazy-loaded tree with retained size bars, field names, and action buttons |\n| **Leak Suspects** | Objects/classes retaining \u003e10% of heap, with adjustable threshold slider |\n| **Waste** | Duplicate strings, empty collections, over-allocated arrays, boxed primitives |\n| **Source** | Jump to Java source — workspace files, Maven/Gradle dependency JARs, or CFR decompilation |\n| **Query** | HeapQL: SQL-like queries with autocomplete, syntax highlighting, and query history |\n| **Compare** | Diff two heap dumps — class deltas, leak changes, waste delta, export as markdown or CSV |\n| **Timeline** | Multi-snapshot trend analysis with D3.js line charts |\n| **AI Chat** | Ask questions in English — get HeapQL queries and insights |\n\n![Heap Composition](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/heap_composition.png)\n![Leak Suspects](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/leak_suspects.png)\n\n### Dominator Tree Actions\n\nEvery node in the dominator tree has one-click actions:\n\n- **Why alive?** — shows the shortest GC root path as a breadcrumb\n- **Inspect** — opens a field-level inspector panel with primitive values and reference links\n- **Go to source** — jumps to the `.java` file (workspace, dependency JAR, or decompiled)\n- **Show referrers** — \"Who references this object?\" with recursive drill-down\n\n![Dominator Tree](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/dominator_tree.png)\n![Explain Object](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/explain_object.png)\n\n### HeapQL Query Language\n\nA SQL-like language purpose-built for heap analysis:\n\n```sql\n-- Find all HashMaps retaining more than 1MB\nSELECT * FROM instances\nWHERE class_name = 'java.util.HashMap' AND retained_size \u003e 1MB\nORDER BY retained_size DESC\n\n-- Top 10 classes by total retained size (with column aliases)\nSELECT class_name, COUNT(*) AS instance_count, SUM(retained_size) AS total_retained\nFROM class_histogram\nGROUP BY class_name\nORDER BY total_retained DESC LIMIT 10\n\n-- JOIN instances with class histogram\nSELECT * FROM instances i\nJOIN class_histogram c ON class_name = class_name\nWHERE i.retained_size \u003e 1MB LIMIT 10\n\n-- Subquery: objects larger than average\nSELECT * FROM instances\nWHERE retained_size \u003e (SELECT AVG(retained_size) FROM instances)\nORDER BY retained_size DESC LIMIT 10\n\n-- GC root path for a specific object\n:path 123456789\n\n-- Who references this object?\n:refs 123456789\n```\n\n- **Tables:** `instances`, `class_histogram`, `dominator_tree`, `leak_suspects`\n- **JOINs:** `INNER JOIN`, `LEFT JOIN` with table aliases\n- **Aggregates:** `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` with `AS` aliases\n- **Subqueries:** `WHERE col IN (SELECT ...)`, `WHERE col \u003e (SELECT AVG(...) FROM ...)`\n- **Size literals:** `1KB`, `5MB`, `1GB`\n\n![HeapQL Query](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/query.png)\n\n### AI-Powered Analysis\n\nConfigure 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):\n\n\u003e *\"What's causing the high memory usage?\"*\n\u003e *\"Show me the top 10 classes by retained size\"*\n\u003e *\"Why is this HashMap so large?\"*\n\nThe LLM responds with explanations **and** runnable HeapQL queries. Click **Run Query** to execute them inline.\n\n![AI Chat](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/ai_chat.png)\n![Fix Recommendation](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/fix_recommendation.png)\n\n### Instance Enumeration\n\nClick any class name in the **Histogram** tab to see all instances of that class. Each instance row has action buttons for inspect, show referrers, and \"Why alive?\" — no need to manually write queries.\n\n![Histogram](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/histogram.png)\n\n### Source Code Bridge\n\nThree-tier source resolution:\n\n1. **Workspace** — finds `.java` files in your project\n2. **Dependencies** — extracts from Maven/Gradle source JARs (`~/.m2`, `~/.gradle`)\n3. **Decompilation** — falls back to CFR decompiler when source JARs are unavailable\n\n![View Source](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/view_source.png)\n![Source](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/source.png)\n\n### Waste Detection\n\nFinds memory waste patterns automatically:\n\n- **Duplicate strings** — identical string values held multiple times\n- **Empty collections** — `HashMap`, `ArrayList`, etc. with zero elements\n- **Over-allocated collections** — arrays sized far beyond their element count\n- **Boxed primitives** — `Integer`, `Long`, etc. that could be primitive\n\n![Waste Detection](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/waste.png)\n\n### Snapshot Comparison \u0026 Timeline\n\n- **Compare** two heap dumps: summary delta, class-level growth/shrinkage with change badges, leak suspect changes (new/resolved/persisted), waste delta, and a D3.js bar chart of top changes.\n- **Copy Report** copies a full markdown diff report to clipboard.\n- **Export CSV** saves all class changes to a file.\n- **Timeline** multiple snapshots: track heap growth trends over time with interactive charts.\n\n![Compare](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/compare.png)\n\n---\n\n## Getting Started\n\n1. **Install** HeapLens from the VS Code Marketplace\n2. **Open** any `.hprof` file — HeapLens activates automatically\n3. **Explore** the 10 tabs: Overview for a summary, Histogram to find big classes, Dominator Tree to drill down\n\n![Loading HPROF](https://raw.githubusercontent.com/sachinkg12/heaplens/main/media/screenshots/Hprof_loading.png)\n\n### Generate a Heap Dump\n\n```bash\n# From a running JVM\njmap -dump:format=b,file=heap.hprof \u003cpid\u003e\n\n# On OutOfMemoryError (add to JVM args)\n-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./heap.hprof\n\n# Android (via adb)\nadb shell am dumpheap \u003cpid\u003e /data/local/tmp/heap.hprof\nadb pull /data/local/tmp/heap.hprof\n```\n\n### AI Chat Setup (Optional)\n\n1. Go to **Settings** \u003e search `heaplens.llm`\n2. Set `heaplens.llm.provider` to your preferred provider (Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Groq, xAI, Together AI, OpenRouter, or Ollama)\n3. Set `heaplens.llm.apiKey` to your API key (not needed for Ollama)\n4. Open the **AI Chat** tab and start asking questions\n\n---\n\n## Settings\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `heaplens.llm.provider` | `anthropic` | LLM provider (anthropic, openai, gemini, deepseek, mistral, groq, xai, together, openrouter, ollama) |\n| `heaplens.llm.apiKey` | — | API key for the LLM provider |\n| `heaplens.llm.baseUrl` | — | Custom API base URL (for proxies or self-hosted) |\n| `heaplens.llm.model` | — | Model name override |\n| `heaplens.sourceResolution.enabled` | `true` | Enable dependency source JAR resolution |\n| `heaplens.sourceResolution.mavenHome` | — | Custom Maven repository path |\n| `heaplens.sourceResolution.gradleHome` | — | Custom Gradle cache path |\n| `heaplens.sourceResolution.decompilerEnabled` | `true` | Enable CFR decompilation fallback |\n\n---\n\n## Architecture\n\n```\nVS Code Extension (TypeScript)\n  └─ HprofEditorProvider (custom editor for .hprof)\n      └─ RustClient (JSON-RPC 2.0 over stdin/stdout)\n          └─ hprof-server (async Rust + tokio)\n              └─ Analysis engine (petgraph dominator tree,\n                 HeapQL query engine, waste analysis)\n```\n\n- **Rust engine** — two-phase architecture with zero-copy mmap parsing, CSR edge storage, Lengauer-Tarjan dominator tree, and rayon-parallelized edge extraction\n- **TypeScript extension** — VS Code custom editor, webview UI, LLM integration\n- **MCP server** — `hprof-server --mcp` for use with Claude Desktop, Cline, and other AI clients\n\n---\n\n## Supported Formats\n\n- Java HotSpot HPROF (JDK 8+) — analyze heap dumps from any JVM application, Spring Boot, microservices, or Kubernetes pods\n- Android HPROF (Dalvik/ART) — debug memory leaks in Android apps directly from `adb` heap dumps\n- HPROF versions: 1.0.1, 1.0.2, 1.0.3\n- Works with heap dumps generated by `jmap`, `jcmd`, `-XX:+HeapDumpOnOutOfMemoryError`, and Android Debug Bridge\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `HeapLens: Analyze HPROF File` | Open a file picker to select and analyze a `.hprof` file |\n| `HeapLens: Export Analysis to JSON` | Export the current analysis results to a JSON file |\n\n---\n\n## Requirements\n\n- VS Code 1.109.0 or later\n- No additional dependencies — the native Rust binary is bundled with the extension\n\n**Optional:**\n- Java on `PATH` (for CFR decompilation fallback)\n- Maven/Gradle project (for dependency source resolution)\n- API key for AI Chat (Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Groq, xAI, Together AI, OpenRouter, or use Ollama for free local models)\n\n---\n\n## Performance\n\nHeapLens uses a native Rust binary with a two-phase CSR architecture for parsing and analysis. Benchmarks on Apple M1 (median of 5 runs):\n\n| Heap Size | Analyze Time | Throughput |\n|-----------|-------------|------------|\n| 1.5 GB | ~0.9 s | 1,687 MB/s |\n| 2 GB | ~1.2 s | 1,645 MB/s |\n| 14 GB | ~10.5 s | 1,365 MB/s |\n\n---\n\n## Telemetry\n\nHeapLens collects anonymous usage telemetry (feature adoption, analysis performance) via Azure Application Insights to help improve the extension. **No PII, file paths, code content, or API keys are collected.** Telemetry respects VS Code's `telemetry.telemetryLevel` setting — set it to `off` to disable all telemetry.\n\n---\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsachinkg12%2Fheaplens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsachinkg12%2Fheaplens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsachinkg12%2Fheaplens/lists"}