JVM Garbage Collection Pause Analysis Prompt

This prompt is designed for performance engineers and SREs who need to move from a GC pause alert to a specific, code-aware tuning recommendation. It is intended for a coding agent or LLM that has access to repository source code, GC log files, and runtime metrics. The core job-to-be-done is correlating a specific pause spike event with allocation hot spots in your application's codebase, producing a hypothesis that is grounded in your actual objects and data structures rather than generic JVM flag suggestions. The ideal user is an engineer who has already identified a problematic GC event in a log and needs to understand why the application allocated memory in that way at that moment.

Use this prompt when you have a specific GC log file showing a pause spike and you need a hypothesis grounded in your application's actual allocation patterns. The required context includes: a GC log snippet covering the pause event, the relevant application source code (or the agent's ability to search it), and basic runtime metrics like heap size and allocation rate. Do not use this for initial JVM setup, capacity planning without an active incident context, or when you lack access to the application source code. The prompt is also inappropriate for analyzing systemic, long-term memory pressure that requires a histogram of allocation sites over hours; it is scoped to a single, high-impact pause event.

Before invoking this prompt, ensure you have isolated the specific GC event you want to analyze. The prompt forces the model to cite specific code locations and allocation paths, so if the agent cannot access the repository, it will fail to produce a useful answer. The output is a structured recommendation, not a general discussion. If you need a broader GC strategy review or a capacity model, use a different workflow. After receiving the output, validate the cited code paths manually and test any suggested JVM flag changes in a staging environment before production rollout.

This prompt template is designed to be wired directly into your AI coding agent or LLM harness. It expects structured GC log data, heap metrics, and allocation profiles as input, and it produces a GC tuning recommendation with quantified pause reduction estimates. The square-bracket placeholders allow you to inject runtime context, constraints, and output formatting requirements without modifying the core diagnostic logic.

textCopy
You are a JVM performance engineer analyzing garbage collection pause spikes in a production Java application.

## Input Data
- GC Log Excerpt: [GC_LOG_SNIPPET]
- Heap Composition Snapshot: [HEAP_COMPOSITION]
- Allocation Rate Profile: [ALLOCATION_RATE_PROFILE]
- Application Throughput Metrics: [THROUGHPUT_METRICS]
- JVM Version and GC Algorithm: [JVM_VERSION_AND_GC]
- Relevant Source Code Allocation Hot Spots: [ALLOCATION_HOTSPOTS]

## Analysis Constraints
[CONSTRAINTS]

## Required Output Schema
[OUTPUT_SCHEMA]

## Task
1. Parse the GC log excerpt and identify pause events by duration, collector type (Young, Mixed, Full), and frequency.
2. Correlate pause patterns with heap composition: eden occupancy, survivor usage, old gen fragmentation, humongous allocations, and metaspace pressure.
3. Map allocation rate spikes to the provided source code hot spots and throughput metrics.
4. Classify the root cause into one or more of: young gen undersizing, survivor space overflow, premature promotion, humongous allocation fragmentation, old gen fragmentation, metaspace exhaustion, or systemic allocation pressure.
5. Produce a GC tuning recommendation that includes:
   - Specific JVM flag changes with before/after values
   - Expected pause reduction estimate (range in milliseconds and percentage)
   - Code-level allocation fixes if applicable
   - Rollback guidance and monitoring thresholds
6. Flag any recommendation that requires production testing before full rollout.

## Output Format
Return a JSON object matching the provided output schema exactly. Include a `confidence` field (0.0 to 1.0) for each root cause classification. If insufficient data exists to reach a conclusion, set `requires_more_data` to true and specify which metrics are missing.

## Evidence Grounding
Every tuning recommendation must cite specific GC log lines, heap metric values, or allocation hot spots as evidence. Do not recommend flag changes without correlating them to observed pause patterns.

To adapt this prompt for your environment, replace each placeholder with real data from your observability stack. The [GC_LOG_SNIPPET] should include at least 60 seconds of GC activity surrounding the pause spike. The [OUTPUT_SCHEMA] placeholder should contain your team's expected JSON structure, including fields for root cause classification, flag recommendations, and pause reduction estimates. For high-risk production systems, add a [RISK_LEVEL] constraint that gates aggressive tuning recommendations behind explicit human approval. Before shipping, validate the prompt against at least five historical GC incidents where the root cause is known, and measure whether the model's recommendations match the actual remediation that resolved the incident.

This prompt is designed to be the reasoning core of an automated GC investigation agent, not a one-off chat interaction. The implementation harness must feed the prompt structured, validated inputs from a live JVM or a historical archive, then parse its structured output to drive a recommendation engine. The primary integration points are a GC log parser, a heap dump analyzer, and an application performance monitoring (APM) metrics API. The harness should never pass raw, multi-gigabyte heap dumps or unstructured log files directly to the model. Instead, it must pre-process them into the summarized statistical format the prompt expects: pause time percentiles, heap composition by region, allocation rate trends, and a list of top allocation sites from a CPU sampling profiler. This pre-processing step is the most critical part of the harness because it enforces the token budget and prevents the model from hallucinating on unparsed binary data.

The implementation should follow a strict pipeline: (1) Validate Inputs: Confirm that GC log duration, heap dump timestamp, and APM metrics all cover the same incident window. Reject the run if the time windows drift by more than 120 seconds. (2) Assemble Context: Populate the [GC_LOG_SUMMARY], [HEAP_COMPOSITION], [ALLOCATION_HOTSPOTS], and [APPLICATION_THROUGHPUT] placeholders with pre-computed statistics. (3) Invoke Model: Use a model with strong reasoning capabilities and a 200k+ token context window, such as claude-sonnet-4-20250514 or gpt-4o. Set the temperature to 0.1 for deterministic analysis. (4) Validate Output: Parse the model's response against the expected JSON schema. If the recommended_action field is TUNE_GENERATIONAL_SIZES but the expected_pause_reduction_percent is null, flag the output for human review. (5) Log and Store: Write the full prompt, response, and validation result to an audit log for post-hoc analysis of tuning decisions. (6) Human Gate: If the risk_level field is HIGH or the recommended action involves JVM flag changes (-XX flags), route the recommendation to a human performance engineer for approval before any automated execution.

For retries, implement a single retry on schema validation failure with a stripped-down prompt that asks the model to repair only the malformed fields. Do not retry more than once to avoid burning tokens on a fundamentally bad analysis. Common failure modes in production include: the GC log parser missing a concurrent GC cycle and under-reporting pause time, the heap dump being from a different JVM instance than the GC logs, and the model confidently recommending a -XX:MaxGCPauseMillis target that is physically impossible given the observed allocation rate. Your harness should catch these by cross-validating the input sources before the prompt is ever assembled. The next step is to build a small golden dataset of five known GC incidents with expert-written root cause analyses, then run this harness against them to calibrate your validation thresholds before deploying to production.