Performance Tuning

Java Performance Tuning Guide (JDK 17 baseline)

This skill uses JDK 17 as the baseline, organized by "optimization layer -> decision table -> optimization points", covering 4 layers of performance optimization. All optimizations should follow the principle of measure first, then tune -- never guess based on experience.

Boundary with jvm-troubleshoot:

• jvm-troubleshoot: Production issues already occurred (OOM/CPU 100%/deadlock) -> follow "symptom -> diagnosis -> fix" to investigate
• This skill: Code/configuration hasn't broken yet, but you want it faster -> follow "layer -> selection -> optimization" to prevent issues

Optimization Layer Quick Reference

Performance Optimization Decision Flow

Always follow this order, never skip steps:

1. Measure baseline first: Use JMH or Profiling to get current performance numbers (throughput/latency/P99). No data, no optimization.
2. Locate bottleneck layer: Use Profiling (async-profiler / JFR) to see which of CPU/memory/locks/IO is the hotspot.
3. Optimize from the top layer down: Business algorithm > Data structure > Code style > JVM parameters > Hardware
   • Changing algorithm from O(n^2) to O(n log n) yields far more benefit than tuning JVM parameters.
4. Change only one variable at a time: After each change, re-measure and compare before/after data.
5. Don't stop until the target is met: Performance optimization is an iterative process, not a one-shot deal.

Anti-patterns:

• Adjusting -Xmx and GC parameters without measuring -> mostly no benefit
• Deploying code changes without running JMH -> no idea if it got faster or slower
• Assuming Stream/parallelStream is always faster -> many scenarios are slower than for loops
• Forcing reflection in JDK 17 without --add-opens -> InaccessibleObjectException

JVM Parameter Tuning

Heap Size Decision

Rules of thumb:

• Bigger heap is not always better. 32GB+ disables compressed oops (-XX:+UseCompressedOops), object references become 8 bytes, actually consuming more memory.
• Inside containers: -XX:+UseContainerSupport (enabled by default in JDK 17), lets JVM recognize container memory limits.
• Using percentages is more convenient: -XX:InitialRAMPercentage=50.0 -XX:MaxRAMPercentage=75.0

Stack Size Tuning

GC Collector Selection

JDK 17 stable collectors:

JDK 17 ZGC key point: Non-generational version (generational ZGC is stable only in JDK 21+). Heap > 32GB + throughput-sensitive -> upgrade to JDK 21.

Selection decision:

1. JDK 17 + heap >= 8GB + low latency -> prefer ZGC
2. JDK 17 + heap < 8GB -> G1 (default)
3. Throughput first (offline computation) -> Parallel
4. Heap > 32GB + throughput-sensitive -> upgrade to JDK 21 generational ZGC

Do not:

• Use ZGC with heap < 4GB -> no benefit
• Switch collectors without measuring -> might be slower
• Set -XX:MaxGCPauseMillis=1 -> mostly unachievable, causes frequent GC instead

See references/gc_tuning.md for more GC tuning details.

Key JVM Parameter Quick Reference

Monitoring (commonly enabled in JDK 17 production):

-Xlog:gc*:file=gc.log:time,uptime:filecount=10,filesize=10M   # GC log
-XX:+HeapDumpOnOutOfMemoryError                                # Auto dump on OOM
-XX:HeapDumpPath=/var/log/dumps/                              # dump path
-XX:ErrorFile=/var/log/hs_err_%p.log                           # Fatal error log
-XX:StartFlightRecording=filename=/var/log/jfr/app.jfr,maxage=1h,maxsize=100M,settings=profile  # JFR always on

Common tuning parameters:

-Xms4g -Xmx4g                              # Initial/max heap, equal to avoid expansion
-XX:MetaspaceSize=256m                     # Initial Metaspace
-XX:MaxMetaspaceSize=512m                  # Metaspace upper limit
-XX:+DisableExplicitGC                     # Disable System.gc()
-XX:+AlwaysPreTouch                        # Pre-touch all pages at startup
-XX:ParallelGCThreads=N                    # GC thread count, default CPU cores * 5/8
-XX:ConcGCThreads=N                        # Concurrent GC thread count, default ParallelGCThreads * 1/4

JIT-related:

-XX:+TieredCompilation                     # Tiered compilation (enabled by default in JDK 17)
-XX:ReservedCodeCacheSize=256m             # JIT code cache; too small triggers deoptimization

Module system (JDK 17 must-know):

--add-opens java.base/java.lang=ALL-UNNAMED            # Reflective access to String internals
--add-opens java.base/java.util=ALL-UNNAMED            # Reflective access to collection internals
--add-opens java.base/java.nio=ALL-UNNAMED             # Netty reflective access to NIO

See references/jvm_params.md for the complete JVM parameter list.

Code-Level Performance

Collection Selection

Select collections based on access patterns; don't default to ArrayList/HashMap:

HashMap with known size, adjust capacity: new HashMap<>(expectedSize / 0.75 + 1) to avoid resizing.

See references/code_level_optimization.md for more collection optimization details.

Stream Performance

Stream is not a performance optimization tool; it is a readability tool. Using it incorrectly can be slower:

Stream anti-patterns:

• stream().collect(toList()).stream() -- redundant boxing
• list.parallelStream() on small collections -- ForkJoin splitting overhead > benefit
• stream.forEach(x -> sb.append(x)) -- use collect(joining(","))

Reflection Optimization

Reflection is slow but useful. Optimization path:

JDK 17 module system: Reflective access to non-exported packages requires --add-opens, otherwise InaccessibleObjectException.

Lock Optimization

Finer locks are not always better. Lock optimization has 4 levels:

Lock selection decision:

JDK 17 New Features

Virtual threads: Only stable in JDK 21+, not available in JDK 17. JDK 17 alternative: use CompletableFuture / Reactor.

See references/code_level_optimization.md for more code-level optimization details.

Compilation Optimization

JIT Tiered Compilation

JDK 17 enables tiered compilation by default, with 5 tiers:

Warmup:

• Method invocation count reaches threshold (default 10000) to trigger C1 -> C2 compilation
• Long-running applications (production services) stabilize after warmup; short-running applications (CLI/batch) may run entirely in interpreted mode
• Short-running applications should consider GraalVM Native Image or CDS

Code cache: -XX:ReservedCodeCacheSize=256m (JDK 17 default 240M); too small triggers deoptimization.

See references/jit_compiler.md for more JIT details.

Inlining Optimization

Inlining is JIT's most important optimization. Help inlining:

• Don't write hot methods too large (< 35 bytecodes, -XX:MaxInlineSize)
• Add final to classes/methods to help JIT determine non-virtual calls -> inlining
• Use sealed class (JDK 17) to let JIT know all implementations -> monomorphic inlining
• Don't use complex inheritance hierarchies on hot paths (virtual methods are hard to inline)

Anti-patterns:

• Complex inheritance hierarchies on hot paths -> virtual method polymorphism, no inlining
• Using reflection on hot paths -> JIT has difficulty optimizing
• Lambda capturing variables on hot paths -> creates Lambda object each time

Performance Testing & Profiling

JMH Benchmarking

JMH is OpenJDK's Java benchmarking framework, the only trustworthy Java microbenchmark tool.

When to use JMH: Verify if a coding pattern is faster, measure method throughput/latency, compare before/after optimization.

When not to use JMH: Measure entire application performance (use Profiling + integration testing), measure IO-intensive scenarios (JMH is inaccurate), measure one-time initialization (not JMH's design goal).

Minimal JMH usage:

@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@Warmup(iterations = 5, time = 1)
@Measurement(iterations = 5, time = 1)
@Fork(2)
@State(Scope.Thread)
public class CollectionBenchmark {

    @Param({"100", "1000", "10000"})
    int size;

    List<Integer> list;

    @Setup
    public void setup() {
        list = IntStream.range(0, size).boxed().collect(toList());
    }

    @Benchmark
    public int forEachSum() {
        int sum = 0;
        for (int x : list) sum += x;
        return sum;
    }

    @Benchmark
    public int streamSum() {
        return list.stream().mapToInt(Integer::intValue).sum();
    }
}

JMH pitfalls: Must use @Fork(2), must have sufficient @Warmup, don't new objects inside benchmark methods, avoid dead code elimination (use Blackhole).

JDK 17 JMH notes:

• Reflective access to non-exported packages requires --add-opens: @Fork(jvmArgsAppend = {"--add-opens", "java.base/java.lang=ALL-UNNAMED"})
• Vector API benchmark requires --add-modules jdk.incubator.vector

See references/jmh_profiling.md for more JMH details.

Profiling Tools

Select tools by granularity:

JDK 17 JFR advantages: Streaming API (JDK 14+) enables real-time streaming consumption of events without disk persistence. settings=profile provides more complete events. Commonly enabled in production: -XX:StartFlightRecording=....

async-profiler flame graph:

./profiler.sh -d 30 -f flame.html <pid>            # CPU
./profiler.sh -d 30 -e alloc -f alloc.html <pid>    # Allocation
./profiler.sh -d 30 -e lock -f lock.html <pid>      # Lock

Performance Metrics System

Metric pitfalls: Only looking at average latency without P99 -> long tail is hidden; only looking at throughput without latency -> high QPS may rely on request queuing; drawing conclusions from a single benchmark -> use statistically significant multiple measurements.

Real-World Cases

Reference 6 end-to-end cases with complete tuning workflows:

See references/tuning_cases.md for detailed cases.

AI Agent Framework Optimization

agent-core-java is an AI agent framework with specific performance bottlenecks different from general Java applications.

LLM calls account for 90%+ of time. Code-level optimization has limited benefit, but don't let the code layer become a drag.

Optimization Layers

Agent Framework Performance Bottleneck Distribution

User input -> prompt concatenation -> LLM HTTP call (slowest) -> JSON parsing -> Tool invocation (reflection) -> Response concatenation

LLM HTTP calls account for 90%+ of time. Code-level optimization has limited benefit, but every microsecond of latency accumulates into milliseconds under high QPS.

See references/ai_agent_optimization.md for detailed optimization (including OkHttp / Jackson / reflection / prompt / async orchestration / caching strategies + practical checklist).

Reference Entry Points

• JVM Parameter Details: references/jvm_params.md (JDK 17 default parameter table, heap/stack/Metaspace/CodeCache/JIT parameter values)
• GC Tuning: references/gc_tuning.md (proactive configuration, complements jvm-troubleshoot)
• Code-Level Optimization: references/code_level_optimization.md (collections/Stream/reflection/locks/escape analysis + JDK 17 new features)
• JIT & Compilation Optimization: references/jit_compiler.md (tiered compilation, inlining, Vector API, GraalVM)
• JMH & Profiling: references/jmh_profiling.md (JMH API, pitfalls, JFR, flame graph reading)
• Real-World Cases: references/tuning_cases.md (6 end-to-end optimization cases)
• AI Agent Framework Optimization: references/ai_agent_optimization.md (LLM calls, JSON serialization, reflection, prompt, async, caching)
• In-project incident troubleshooting: ../jvm-troubleshoot/SKILL.md (reactive investigation after problems occur)
• In-project coding standards: ../coding-standard/SKILL.md
• Official documentation: https://docs.oracle.com/en/java/javase/17/docs/specs/man/
• JMH official: https://openjdk.org/projects/code-tools/jmh/
• async-profiler: https://github.com/async-profiler/async-profiler
• JFR / JDK Mission Control: https://github.com/openjdk/jmc

Usage

1. Start with the decision flow: Performance optimization follows "measure -> locate -> optimize -> re-measure"; don't skip steps
2. Look up by layer: JVM parameters -> Code-level -> Compilation -> Testing; use the "Optimization Layer Quick Reference" table to jump
3. Read details on demand: Each section points to the corresponding references file
4. Does not replace jvm-troubleshoot: For production issues (OOM/CPU 100%), use the incident troubleshooting skill
5. Don't guess based on experience: All optimizations must be verified with JMH or Profiling
6. Don't fabricate when uncertain: JVM/JIT behavior should be based on source code and official documentation; this skill does not replace formal documentation