java-best-practices-debug-analyzer（Java 最佳实践调试分析器）

Works with Java exception logs, thread dumps, heap dumps, and error messages.

Java Debug Analyzer

Table of Contents

• Purpose
• When to Use
• Quick Start
• Instructions
• Examples
• Requirements
• Analysis Checklist
• Output Format
• Error Handling

Purpose

Analyzes Java runtime issues, exceptions, stack traces, thread dumps, and performance problems to identify root causes and provide actionable solutions. Helps debug common Java errors, memory leaks, concurrency issues, and performance bottlenecks.

When to Use

Use this skill when you need to:

• Debug Java runtime exceptions (NullPointerException, ClassNotFoundException, etc.)
• Analyze stack traces to find root causes
• Investigate memory leaks (OutOfMemoryError)
• Debug performance issues (slow responses, high CPU/memory)
• Analyze thread dumps for deadlocks or thread contention
• Diagnose ClassNotFoundException or NoClassDefFoundError
• Troubleshoot database connection issues
• Debug concurrency problems (race conditions, deadlocks)
• Investigate production errors from logs
• Root cause analysis for Java application failures

Quick Start

Provide any Java error, exception, or log and receive root cause analysis:

# Analyze a stack trace
Analyze this Java stack trace: [paste stack trace]

# Debug an exception in logs
Debug the errors in application.log

# Analyze thread dump
Analyze the thread dump in thread-dump.txt

Instructions

Step 1: Identify Problem Type

Classify the issue to apply appropriate analysis:

Exception Categories:

• Runtime exceptions (NullPointerException, ClassCastException, etc.)
• Checked exceptions (IOException, SQLException, etc.)
• Custom application exceptions
• Framework exceptions (Spring, Hibernate, etc.)

Performance Issues:

• Slow response times
• High CPU usage
• High memory consumption
• Thread contention

Resource Issues:

• Memory leaks
• Connection pool exhaustion
• File handle leaks
• Thread starvation

Configuration Issues:

• ClassNotFoundException/NoClassDefFoundError
• Dependency conflicts
• Property misconfiguration

Step 2: Analyze Stack Traces

Extract critical information from stack traces:

Key Elements to Identify:

1. Exception type - What went wrong
2. Exception message - Why it happened
3. Caused by chain - Root cause
4. First application frame - Where in your code
5. Framework frames - Context of execution
6. Suppressed exceptions - Additional context

Analysis Pattern:

Read stack trace from bottom to top:
1. Find "Caused by" at the bottom (root cause)
2. Identify the first frame in YOUR code
3. Understand the context from framework frames
4. Look for patterns (repeated exceptions, timing)

Step 3: Diagnose Common Exceptions

NullPointerException

Root Causes:

• Uninitialized object reference
• Method returning null not handled
• Optional not checked
• Missing null checks in chain calls

Analysis Steps:

1. Identify exact line from stack trace
2. Examine variables on that line
3. Trace back to where null originated
4. Check method contracts (should it return null?)

Example Analysis:

// Stack trace shows:
Exception in thread "main" java.lang.NullPointerException
    at com.example.UserService.getEmail(UserService.java:45)

// Line 45 is:
String email = user.getEmail().toLowerCase();

// Diagnosis: Either user is null OR user.getEmail() returns null
// Solution: Add null checks or use Optional
String email = Optional.ofNullable(user)
    .map(User::getEmail)
    .map(String::toLowerCase)
    .orElse("no-email");

ClassNotFoundException / NoClassDefFoundError

Difference:

• ClassNotFoundException: Class not found at runtime (missing in classpath)
• NoClassDefFoundError: Class was present at compile time but missing at runtime

Root Causes:

• Missing dependency in pom.xml/build.gradle
• Dependency version conflict
• Wrong classpath configuration
• JAR not packaged correctly

Analysis Steps:

1. Identify the missing class name
2. Check if dependency is declared
3. Verify dependency scope (runtime vs compile)
4. Check for version conflicts (mvn dependency:tree)

OutOfMemoryError

Types:

• Java heap space - Object allocation failed
• GC overhead limit exceeded - Too much time in GC
• Unable to create new native thread - Thread exhaustion
• Metaspace - Class metadata exhaustion

Analysis Steps:

1. Identify OOM type from message
2. Check heap size configuration (-Xmx)
3. Look for memory leak patterns
4. Analyze heap dump if available

Step 4: Analyze Thread Dumps

Understand thread states and identify issues:

Thread States:

• RUNNABLE - Executing or ready to execute
• BLOCKED - Waiting for monitor lock
• WAITING - Waiting indefinitely (Object.wait())
• TIMED_WAITING - Waiting with timeout (Thread.sleep())
• TERMINATED - Thread finished execution

Red Flags:

• Multiple threads BLOCKED on same lock (contention)
• Many threads in WAITING state (possible deadlock)
• Threads holding locks for long time
• Repeated stack patterns (infinite loops)

Deadlock Detection Pattern:

Look for:
1. Thread A: waiting to lock <0x123> held by Thread B
2. Thread B: waiting to lock <0x456> held by Thread A

Step 5: Diagnose Performance Issues

High CPU:

• Look for infinite loops in thread dumps
• Check for inefficient algorithms (nested loops)
• Examine regex patterns (catastrophic backtracking)
• Verify GC frequency (excessive GC)

High Memory:

• Large collections not cleared
• Static references preventing GC
• Memory leaks from listeners/callbacks
• Caching without size limits

Slow Queries:

• Missing database indexes
• N+1 query problems
• Large result sets
• Missing query optimization

Step 6: Provide Root Cause and Solution

Output Format:

## Problem Summary
[Brief description of the issue]

## Root Cause
[Detailed explanation of why this happened]

## Evidence
[Stack traces, log excerpts, analysis data]

## Solution
[Step-by-step fix]

## Prevention
[How to avoid this in the future]

Supporting Files

Requirements

• Java development experience
• Understanding of stack traces
• Familiarity with Java exceptions
• Basic knowledge of JVM internals (for memory/thread issues)

Red Flags to Avoid

• Do not ignore root causes - treat symptoms only temporarily
• Do not skip stack trace analysis - every line contains clues
• Do not assume - verify with evidence from logs/code
• Do not provide generic solutions - tailor to specific error
• Do not forget prevention - suggest long-term fixes
• Do not ignore thread dumps - they reveal concurrency issues
• Do not overlook memory patterns - heap dumps show object retention

Notes

• Always analyze the full stack trace, not just the first line
• Root cause is often several frames deep in the stack
• Consider the context: production load, data volume, timing
• Memory issues often have delayed manifestations
• Thread dumps require comparing multiple snapshots
• ClassNotFoundException vs NoClassDefFoundError are different issues
• Performance problems often stem from inefficient algorithms or database queries