Debugging and Troubleshooting
1. Using JDWP (Java Debug Wire Protocol)
| Aspect | Detail |
|---|---|
| Protocol | Wire format between debugger and JVM |
| JDI | Java Debug Interface (debugger side) |
| JVMTI | Native back-end on JVM side |
| Transports | dt_socket, dt_shmem (Windows) |
2. Setting Breakpoints
| Type | Use |
|---|---|
| Line breakpoint | Pause at line |
| Method breakpoint | Enter / exit |
| Field watchpoint | On read / write |
| Exception breakpoint | On throw / uncaught |
| Conditional | Expression must be true |
| Hit count | Trigger after N hits |
3. Using Remote Debugging (-agentlib:jdwp)
Example: Enable remote debug
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar| Option | Use |
|---|---|
| server=y | JVM listens |
| suspend=y | Wait for debugger before main |
| address=*:5005 | Bind any iface (Java 9+ requires *) |
Warning: JDWP allows arbitrary code execution. NEVER expose port to untrusted networks. Bind to
localhost in production diagnostics or tunnel via SSH.
4. Analyzing Stack Traces
| Element | Meaning |
|---|---|
| Caused by | Underlying exception |
| Suppressed | From try-with-resources close |
| at A.b(File.java:42) | Frame: class.method(source:line) |
| N more | Identical tail elided |
| Helpful NPE (Java 14+) | Pinpoints null subexpression |
5. Using Logging Frameworks
| Framework | Use |
|---|---|
| SLF4J | Facade — code against |
| Logback | Recommended impl |
| Log4j 2 | Async + GC-free modes |
| JUL (java.util.logging) | Built-in but limited |
| System.Logger | JDK-neutral facade (Java 9+) |
6. Enabling Assertions (-ea flag)
| Flag | Use |
|---|---|
-ea | Enable all (incl. user code) |
-da | Disable |
-ea:com.acme... | Enable for package |
-esa | Enable system assertions |
Note: Assertions are off by default at runtime. Use only for invariants — never for argument validation in public APIs.
7. Using System.Logger API (Java 9+)
Example: System.Logger
private static final System.Logger LOG = System.getLogger(Foo.class.getName());
LOG.log(System.Logger.Level.INFO, "Started: {0}", id);| Aspect | Detail |
|---|---|
| Provider lookup | ServiceLoader: System.LoggerFinder |
| Default | Wraps JUL if no finder |
| Use | JDK / lib code that wants to honor host logging stack |
8. Debugging Multithreaded Applications
| Tool | Use |
|---|---|
| Thread dump | Snapshot all stacks; find BLOCKED/WAITING |
| Deadlock detection | jcmd PID Thread.print reports cycles |
| JFR Lock Profiling | Contention hotspots |
| tsan / Java Concurrency Stress (jcstress) | Race tests |
9. Using Memory Profilers
| Profiler | Use |
|---|---|
| Eclipse MAT | Heap dump analysis (Dominator Tree, Leak Suspects) |
| VisualVM | Live JMX + sampling |
| JFR alloc events | Sample allocation stacks |
| async-profiler -e alloc | Allocation flame graph |
10. Detecting Performance Bottlenecks
Bottleneck Diagnosis Workflow
- Measure baseline: throughput, p99 latency, CPU, GC %, allocation rate
- Identify resource: CPU-bound vs lock-bound vs I/O-bound vs GC-bound
- Profile with JFR (low overhead) or async-profiler (flame graph)
- Correlate with logs and metrics around the time window
- Fix top offender; re-measure; iterate
| Symptom | Likely Cause |
|---|---|
| High GC % | Allocation pressure / heap too small |
| Many BLOCKED threads | Lock contention on shared monitor |
| Low CPU + slow | I/O wait or external service |
| Spiky latency | Stop-the-world events |
11. Understanding Native Stack Traces
| Source | Detail |
|---|---|
| Crash | hs_err_pid<PID>.log |
| Sections | Signal info, registers, native frames, Java frames |
| JVMCRASH causes | Bad JNI, hardware, JIT bug, OOM-killer |
| Tools | addr2line, JIT-aware perf maps |
12. Using Debug Visualization Tools
| Tool | Use |
|---|---|
| JDK Mission Control | JFR analysis UI |
| VisualVM | Live monitoring + sampler |
| IntelliJ IDEA Debugger | Interactive stepping, smart step into, evaluate-expression |
| Flame graphs | async-profiler / Brendan Gregg's stackcollapse |
| GCViewer / GCEasy | GC log visualization |
| Wireshark | Network-level diagnostics |
Summary
This cheatsheet covers Java 21+ features end-to-end: functional programming (lambdas, Streams, Optional), modern language features (records, sealed classes, pattern matching, text blocks, virtual threads, structured concurrency), runtime APIs (NIO.2, HttpClient, Modules, Class Loading, Instrumentation), JVM internals (memory, GC, JIT, JFR), performance methodology (JMH), security (JCE, TLS, secure coding), Project Panama (FFM API), and troubleshooting workflows. Always prefer modern, safe alternatives (FFM over Unsafe, Cleaner over finalize, virtual threads over thread pools for blocking I/O, ObjectInputFilter for serialization).