Memory Leak Investigation Prompt from Heap Dumps

This prompt is for performance engineers and SREs who have captured a heap dump from a JVM-based application and need to identify the root cause of a memory leak. It is designed to be used when you have already parsed the heap dump with a tool like Eclipse MAT or jhat and have a report of the top retained objects, their allocation sites, and GC behavior. The prompt instructs the model to act as a forensic performance engineer, correlating the heap profile data with the application's source code to pinpoint leak candidates, trace allocation paths, and propose concrete code fixes. Use this when you need a structured, code-aware analysis that goes beyond raw heap numbers.

The ideal user has access to three things: a parsed heap report (retained size histograms, dominator trees, or leak suspect reports), the relevant application source code or repository context, and GC log data showing collection frequency and pause patterns. Without all three, the analysis will be incomplete. The prompt expects you to supply [HEAP_DUMP_REPORT] containing class-level retained memory breakdowns and allocation site stacks, [SOURCE_CODE] for the suspect classes and their callers, and [GC_LOG_SUMMARY] with collection counts, pause durations, and heap occupancy trends. If you only have a raw .hprof file without parsing, run Eclipse MAT's leak suspect report first—this prompt is not a replacement for heap dump parsing tools.

Do not use this prompt when the issue is a slow memory leak that hasn't yet produced a significant retained heap, when you lack source code access for the suspect classes, or when the problem is actually a GC tuning issue rather than a leak (excessive allocation rate without retained growth). For GC tuning, use the JVM Garbage Collection Pause Analysis Prompt instead. For cases where the heap dump is from a third-party library you cannot modify, the prompt can still identify the leak path but will be limited to configuration or usage-pattern fixes rather than code changes. Always validate the model's code fix suggestions against your test suite before deploying—memory leak fixes can introduce subtle concurrency or lifecycle bugs if applied without review.

This template is designed to be copied directly into your AI coding agent or LLM interface. It instructs the model to act as a performance engineer, correlating heap dump analysis with your repository's source code to identify memory leak candidates. The prompt uses square-bracket placeholders for all dynamic inputs—fill these in before execution to ground the analysis in your specific runtime data and codebase.

textCopy
You are a senior performance engineer investigating a memory leak in a production service. Your task is to analyze a heap dump summary and correlate findings with the source code in the repository to identify the most likely leak root causes.

## INPUT DATA

### Heap Dump Summary
[HEAP_DUMP_SUMMARY]

### Top Retained Objects (class name, retained heap, instance count)
[TOP_RETAINED_OBJECTS]

### GC Log Excerpt (last 5 cycles)
[GC_LOG_EXCERPT]

### Allocation Site Hotspots (method, allocated bytes, allocation rate)
[ALLOCATION_SITE_HOTSPOTS]

## REPOSITORY CONTEXT

### Source Code for Suspect Classes
[SOURCE_CODE_SNIPPETS]

### Recent Commits (last 7 days, touching suspect paths)
[RECENT_COMMITS]

### Configuration Files (JVM flags, pool sizes, cache configs)
[CONFIGURATION_FILES]

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "leak_candidates": [
    {
      "suspect_class": "fully.qualified.ClassName",
      "retained_heap_mb": 0,
      "instance_count": 0,
      "allocation_path": "method chain from allocation site to leak",
      "source_file": "path/in/repo/SuspectClass.java",
      "leak_mechanism": "description of why objects are retained (e.g., unclosed resource, growing collection, static reference, listener leak, thread-local accumulation)",
      "evidence_from_code": "specific line or pattern in the source that supports this diagnosis",
      "confidence": "high|medium|low",
      "fix_recommendation": "concrete code change with before/after example"
    }
  ],
  "gc_analysis": {
    "pause_trend": "increasing|stable|decreasing",
    "promotion_failure_rate": 0.0,
    "old_gen_growth_rate_mb_per_minute": 0.0,
    "correlation_with_allocation_sites": "explanation linking GC behavior to allocation hotspots"
  },
  "excluded_candidates": [
    {
      "class_name": "fully.qualified.ClassName",
      "exclusion_reason": "why this class is not a leak despite high retained heap"
    }
  ],
  "investigation_priority": ["ordered", "list", "of", "suspect_classes", "to", "investigate", "first"],
  "requires_human_review": true
}

## CONSTRAINTS
- Ground every leak candidate in specific source code evidence from the provided snippets. Do not speculate without code-level support.
- Distinguish between legitimate caches, buffers, and session state versus unbounded accumulation.
- If GC logs show promotion failures, connect them to specific allocation sites.
- Flag any configuration that could mask or exacerbate the leak (e.g., oversized heap, disabled GC logging).
- If confidence is low for any candidate, explain what additional data would increase it.
- Mark `requires_human_review` as true if any fix involves changing cache eviction policies, connection pool sizes, or JVM flags.

## RISK LEVEL
[HIGH|MEDIUM|LOW]

Adaptation guidance: Replace each bracketed placeholder with real data from your heap analysis tool (Eclipse MAT, JProfiler, YourKit, or jcmd output). For [SOURCE_CODE_SNIPPETS], include only the classes that appear in the top retained objects list—do not dump the entire repository. For [RECENT_COMMITS], filter to commits touching memory-sensitive paths (caches, connection pools, listeners, collections). If you lack GC logs, remove the gc_analysis section from the output schema and note the gap in your instructions. For high-risk production incidents, always set requires_human_review to true and route the output to an on-call engineer before applying any fix.

This prompt is designed to be called programmatically as part of a performance investigation pipeline, not as a one-off chat interaction. The typical integration point is a CI/CD post-deployment analysis step, an on-call runbook automation, or a developer CLI tool that accepts a heap dump path and repository context. The harness must supply the heap dump summary, GC log excerpts, allocation site tables, and relevant source code snippets as structured inputs before invoking the model. Because heap analysis involves large data volumes, pre-processing is essential: extract the top retained objects, dominator tree summaries, and allocation hot spots from the heap dump using tooling like Eclipse MAT or jeprof before passing a condensed representation to the prompt.

Input assembly requires three data sources wired together: (1) a heap dump analyzer that produces a structured JSON summary of retained sizes, class histograms, and GC root paths; (2) a source code indexer that retrieves the relevant allocation-site source files from the repository; and (3) a GC log parser that extracts pause durations, collection counts, and heap occupancy trends. The harness should populate [HEAP_SUMMARY], [GC_LOG_EXCERPTS], [ALLOCATION_SITE_TABLE], and [REPOSITORY_CONTEXT] placeholders from these sources. If any input is missing or incomplete, the harness must abort with a clear error rather than sending a degraded prompt. Model choice matters: use a model with strong code reasoning capabilities and a context window large enough to hold the assembled evidence. For production use, prefer a model that supports structured output constraints so the JSON schema in [OUTPUT_SCHEMA] can be enforced at the API level rather than relying solely on prompt instructions.

Validation and retries are critical because false-positive leak identifications can waste engineering hours. After receiving the model response, validate that every suspect class in the output has a corresponding entry in the input heap summary, that allocation paths reference real source files from the repository context, and that fix recommendations are syntactically plausible for the language in use. If validation fails, retry once with an augmented prompt that includes the specific validation errors. If the second attempt also fails, escalate to a human reviewer with the raw model output and validation failure details. Logging should capture the prompt version, input hashes, model response, validation results, and any retry attempts for auditability and prompt improvement over time.

Human review integration is mandatory when the prompt identifies a leak candidate with high confidence or recommends a fix that changes memory-sensitive code paths such as collection sizing, cache eviction policies, or finalizer logic. The harness should route these outputs to a review queue with the full evidence chain: the original heap summary, the model's reasoning, and the proposed code change. For lower-confidence findings or informational GC tuning suggestions, the harness can surface them as non-blocking recommendations in the developer's existing observability dashboard. Do not wire this prompt directly into an automated code-fix pipeline without human approval, because memory management changes can introduce new regressions that only manifest under production load patterns.