Analyzing Compiler Graphs

Deep-dive tool for understanding Graal compiler optimization decisions at the IR level. Dumps BGV files and analyzes them to reveal exactly what the compiler optimized.

When to Use This Skill

Use AFTER simpler profiling tools when:

• Other tools show problems but don't reveal root cause
• Need to understand WHY optimization fails
• Investigating allocation elimination issues
• Debugging polymorphism and specialization

Prerequisites:

1. ✅ CPU profiling identified hot methods
2. ✅ Performance warnings revealed optimization barriers
3. ✅ Compilation/inlining traces showed issues
4. ✅ bgv2json or Seafoam installed

Quick Start

1. Dump Compiler Graphs

# Basic dump for Truffle compilations
EXTRA_JAVA_ARGS="-Djdk.graal.Dump=Truffle:1 \
  -Djdk.graal.PrintGraph=File \
  -Djdk.graal.DumpPath=compiler_graphs" \
  <launcher> <program>

# Focused dump for specific method (recommended)
EXTRA_JAVA_ARGS="-Djdk.graal.Dump=Truffle:1 \
  -Djdk.graal.MethodFilter='*hotFunction*' \
  -Djdk.graal.DumpPath=compiler_graphs" \
  <launcher> --engine.CompileOnly='*hotFunction*' <program>

2. Analyze with Seafoam

# Get help
seafoam help

# Describe graph characteristics
seafoam --json compiler_graphs/*.bgv.gz:2 describe

# Render to SVG
seafoam compiler_graphs/*.bgv.gz:2 render > graph.svg

3. Convert to JSON for Custom Analysis

bgv2json compiler_graphs/*.bgv > graphs.json

See DUMPING.md for detailed dump options. See QUERIES.md for jq analysis queries.

⚠️ REQUIRED: Fermi Verification (Every Tool Invocation)

Before dumping graphs:

• Pre-calculate: Expected # of BGV files (1 per compiled function, typically 5-20)
• Smoke test: Dump trivial program first → Verify BGV files generated

After dumping:

• Validate: BGV file count within expectation? YES / NO
• If NO: STOP - Check MethodFilter, verify functions compiled
• List BGV files: ls -lh compiler_graphs/*.bgv

After analyzing graphs:

• Validate: Node counts reasonable (thousands, not millions)? YES / NO
• If NO: STOP - May have wrong phase or too broad filter
• Save analysis: tool-outputs/compiler-graph-analysis-[function].txt

Gate: All boxes checked? → Proceed to interpretation

Key Phases to Analyze

Phase	Purpose	What to Check
After TruffleTier	Most important	Direct calls, constant nodes, no VirtualFrame refs
After PartialEscape	Allocation elimination	Zero allocation nodes if EA worked
Final	Generic Graal optimizations	Overall node reduction

Quick Problem Detection

Check for Indirect Calls (Performance Problem!)

seafoam --json file.bgv.gz:2 describe | \
  jq '.node_counts | to_entries | .[] | select(.key | contains("Call"))'

Good: OptimizedDirectCallNode Bad: OptimizedIndirectCallNode, InvokeNode

Check for Failed Escape Analysis

cat graphs.json | jq 'select(.name | contains("After PartialEscape")) |
  .nodes[] | select(.props.label | test("Alloc|New"))'

Good: Empty output Bad: CommitAllocationNode, NewInstanceNode present

Check for Boxing

seafoam --json file.bgv.gz:2 describe | \
  jq '.node_counts | to_entries | .[] | select(.key | test("Box|Unbox"))'

Good: Empty output Bad: BoxNode, UnboxNode present

Node Types Reference

Good Patterns (Optimized)

• OptimizedDirectCallNode - Specialized calls ✅
• AddNode, MulNode, SubNode - Primitive arithmetic ✅
• ConstantNode - Constants from partial evaluation ✅

Bad Patterns (Need Fixes)

• OptimizedIndirectCallNode - Need caching ⚠️
• InvokeNode - Unspecialized method calls ⚠️
• CommitAllocationNode, NewInstanceNode - Escape analysis failed ⚠️
• BoxNode, UnboxNode - Missing primitive specializations ⚠️
• DeoptimizeNode in hot paths - Unstable assumptions ⚠️

Common Problem Patterns

Problem 1: Indirect Calls

Fix: Add @Cached for CallTarget lookup

Problem 2: Failed Escape Analysis

Fix: Keep object lifetime strictly local

Problem 3: Boxing/Unboxing

Fix: Add primitive specializations

See PATTERNS.md for detailed fix examples.

Best Practices

1. Always use MethodFilter - Avoid overwhelming output
2. Start with Level 1 - Only use Level 2 when needed
3. Focus on "After TruffleTier" - Most relevant for language developers
4. Compress BGV files - gzip compiler_graphs/*.bgv
5. Correlate with other tools - Use with TraceCompilation, TracePerformanceWarnings

Related Skills

• profiling-with-cpu-sampler - Identify hot functions FIRST
• detecting-performance-warnings - Find optimization barriers
• tracing-compilation-events - See compilation events
• tracing-inlining-decisions - Check inlining
• detecting-deoptimizations - Find instabilities
• fetching-truffle-documentation - API reference

Detailed Documentation

• DUMPING.md - Dump options and commands
• QUERIES.md - jq analysis queries
• PATTERNS.md - Problem patterns and fixes