From e4b39e4971c231b35f2cc7f50d0b6b330f5da77a Mon Sep 17 00:00:00 2001 From: Yifei Zhang Date: Sun, 20 Jul 2025 22:34:27 -0400 Subject: [PATCH] Add IntelliJ profiler usage guide to developer manual * Add "Development and Debugging Tools" section with IntelliJ JFR profiling guide * Include step-by-step JFR usage, command examples, and interface explanation * Document five analysis windows: Flame Graph, Call Tree, Method List, Timeline, Events * Explain CPU Samples vs Memory Allocations views for performance optimization --- docs/developer/developer-manual.html | 104 +++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/docs/developer/developer-manual.html b/docs/developer/developer-manual.html index 033a12fdd5e8..9db77d4f3206 100644 --- a/docs/developer/developer-manual.html +++ b/docs/developer/developer-manual.html @@ -34,6 +34,10 @@

Checker Framework developer manual
  • Code style
  • IDE configuration
    • +
  • Development and Debugging Tools +
  • Pull requests
    • Branches
      • @@ -281,6 +285,106 @@

      IDE configuration

      +

      Development and Debugging Tools

      + +

      +This section covers various development and debugging tools that can help improve your development experience when working on the Checker Framework. +

      + +

      Profiling with IntelliJ IDEA

      + +

      +IntelliJ IDEA provides powerful profiling capabilities using Java Flight Recorder (JFR) that can help you analyze performance bottlenecks in the Checker Framework. This tool is essential for identifying slow type-checking operations, memory usage patterns, and optimization opportunities. +

      + +

      Step-by-step Usage Guide

      + +

      +Step 1: Generate JFR Profile Data +

      + +

      +First, run the Checker Framework with Java Flight Recorder enabled. Here's a practical example: +

      + +
      +javac -J-XX:+FlightRecorder \
+      -J-XX:StartFlightRecording=duration=30s,filename=nullness-profile.jfr \
+      -processor org.checkerframework.checker.nullness.NullnessChecker \
+      docs/examples/NullnessExample.java
+
      + +

      +Command breakdown: +

      +
        +
      • javac - Java compiler
        • +
      • -J-XX:+FlightRecorder - Enables JFR functionality
        • +
      • -J-XX:StartFlightRecording=duration=30s,filename=nullness-profile.jfr - Starts a 30-second performance recording session, saving results to nullness-profile.jfr file
        • +
      • -processor org.checkerframework.checker.nullness.NullnessChecker - Uses the Nullness Checker for static analysis
        • +
      • docs/examples/NullnessExample.java - Target Java file to analyze
        • +
      + +

      +Step 2: Open JFR File in IntelliJ +

      + +

      +After the command completes, you'll have a nullness-profile.jfr file. To analyze it in IntelliJ: +

      +
        +
      1. Simply double-click the nullness-profile.jfr file
        2. +
      2. IntelliJ IDEA will automatically open and display the JFR Profiler tool window
        3. +
      + +

      +Step 3: Understanding the Profiler Interface +

      + +

      +The profiler window contains several important views: +

      + +
      Understanding the Five Analysis Windows
      +

      +The profiler provides five different views to analyze your application's performance: +

      +
        +
      • Flame Graph: Visual representation of method call hierarchies with execution time proportions. Horizontal bars show method calls, vertical stacks show call chains.
        • +
      • Call Tree: Hierarchical tree view of method calls with detailed timing and percentage information for each call path.
        • +
      • Method List: Flat list of all methods sorted by execution time, allocation count, or other metrics for quick identification of hotspots.
        • +
      • Timeline: Time-based view showing when different operations occurred during the profiling session, useful for understanding execution patterns.
        • +
      • Events: Detailed event log including garbage collection events, class loading, thread activity, and other JVM-level activities.
        • +
      + +
      View Controls (Top Right)
      +

      +The Show dropdown in the top right allows you to switch between different profiling perspectives: +

      + +
        +
      • CPU Samples: +
          +
        • Shows where CPU time is spent during type checking
          • +
        • Identifies bottleneck methods and hot spots
          • +
        • Best for finding slow algorithms or inefficient code paths
          • +
        • Use this to optimize type inference, AST traversal, and annotation processing
          • +
        +
        • +
      • Memory Allocations: +
          +
        • Displays memory allocation patterns and object creation
          • +
        • Helps identify memory-intensive operations
          • +
        • Useful for finding excessive object creation or memory leaks
          • +
        • Important for optimizing type caching and reducing GC pressure
          • +
        +
        • +
      + +

      +See the testing optimizations section for additional performance testing approaches. +

      +

      Pull requests