Adding template for questions about profiling (#91)

* Adding template for questions about profiling
* Improving the cursor rule for step 1
* Adding new cursor rules about profiling
* Removing non necessary file
* Improving README
* Initial round with the new example

Author: jabrena

.cursor/rules/151-java-profiling-detect.mdc

@@ -0,0 +1,262 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Java Profiling Workflow / Step 1 / Collect data to measure potential issues
+
+## ⚠️ CRITICAL INSTRUCTION FOR AI ASSISTANTS ⚠️
+
+**WHEN USING THE PROFILING SCRIPT TEMPLATE:**
+- **COPY THE BASH SCRIPT EXACTLY** from `java-profiling-script-template.md`
+- **NO MODIFICATIONS, INTERPRETATIONS, OR ENHANCEMENTS** allowed
+- **USE EVERY LINE VERBATIM** - do not change logic, structure, or features
+- **DO NOT CREATE YOUR OWN VERSION** - use the provided template only
+- The template script is complete, tested, and production-ready
+
+---
+
+This rule provides comprehensive Java application profiling using async-profiler v4.0, including automatic OS detection, profiler download, and flamegraph generation with the latest features.
+
+## Problem Identification
+
+Before starting the profiling process, identify what specific performance problem you're trying to solve. 
+
+**Reference the profiling questions template:** [java-profiling-questions-template.md](mdc:.cursor/rules/templates/java-profiling-questions-template.md)
+
+The template categorizes problems into:
+- **Performance Bottlenecks** (CPU hotspots, inefficient algorithms, unnecessary allocations, string operations)
+- **Memory-Related Problems** (memory leaks, heap usage, object retention, off-heap issues)
+- **Concurrency and Threading Issues** (lock contention, thread pool issues, deadlocks, context switching)
+- **Garbage Collection Problems** (GC pressure, long pauses, generational issues)
+- **I/O and Network Bottlenecks** (blocking operations, connection leaks, serialization issues)
+
+## Overview
+
+Java profiling helps identify performance bottlenecks, memory leaks, and CPU hotspots in Java applications. This rule automates the process of:
+1. **Problem Identification**: Determine what specific performance issue you're investigating
+2. **Process Detection**: Detecting running Java processes using `jps`
+3. **Environment Setup**: Identifying the operating system and architecture
+4. **Tool Download**: Downloading the appropriate async-profiler v4.0 binary
+5. **Profile Execution**: Attaching to a Java process and generating flamegraphs and heatmaps
+6. **Results Analysis**: Storing and interpreting profiling results
+
+## New Features in v4.0
+
+Based on the [async-profiler v4.0 release](mdc:https:/github.com/async-profiler/async-profiler/releases/tag/v4.0), the latest version includes:
+
+### Major Features
+- **Interactive Heatmaps**: Visualize performance data over time
+- **Native Memory Leak Profiler**: Detect memory leaks in native code
+- **jfrconv Binary**: Enhanced JFR conversion capabilities
+- **Improved JDK 23+ Support**: Full compatibility with the latest JDK versions
+
+### Enhanced Profiling Capabilities
+- **Wall Clock Profiling Optimization**: Better performance for wall-clock profiling
+- **VMStructs-based Stack Walker**: More accurate stack traces with `--cstack vm/vmx`
+- **C API**: Access to thread-local profiling context
+- **Grain Option**: Coarsen flame graphs for better visualization
+- **Inverted Flame Graphs**: Flip flame graphs vertically with `--inverted`
+
+## Project Organization
+
+The profiling setup uses a clean folder structure with everything contained in the profiler directory:
+
+```
+your-project/
+└── profiler/               # ← All profiling-related files
+    ├── scripts/            # ← Profiling scripts and tools
+    │   └── java-profile.sh # ← Main profiling script
+    ├── results/            # ← Generated profiling output
+    │   ├── *.html          # ← Flamegraph files
+    │   └── *.jfr           # ← JFR recording files
+    ├── current/            # ← Symlink to current profiler version
+    └── async-profiler-*/   # ← Downloaded profiler binaries
+```
+
+**Usage:** 
+- Run `./profiler/scripts/java-profile.sh` for comprehensive interactive profiling
+
+## Automated Profiling Script
+
+**IMPORTANT**: Use the exact bash script from the template without any modification or interpretation.
+
+The complete interactive profiling script is available at: [java-profiling-script-template.md](mdc:.cursor/rules/templates/java-profiling-script-template.md)
+
+**CRITICAL INSTRUCTION FOR AI ASSISTANTS:**
+- **COPY THE BASH SCRIPT EXACTLY** from the template file
+- **DO NOT MODIFY, INTERPRET, OR ENHANCE** the script content
+- **DO NOT ADD NEW FEATURES** or change the logic
+- **USE THE SCRIPT VERBATIM** - every line, comment, and function exactly as provided
+- The script is already complete and tested - no improvements needed
+
+**Script Location:**
+```
+└── profiler/               # ← All profiling-related files
+    ├── scripts/            # ← Profiling scripts and tools
+    │   └── java-profile.sh # ← Copy exact script from template
+```
+
+**Setup Instructions:**
+1. Copy the **EXACT** bash script content from `java-profiling-script-template.md` 
+2. Save it as `profiler/scripts/java-profile.sh`
+3. Make it executable: `chmod +x profiler/scripts/java-profile.sh`
+4. **NO MODIFICATIONS** to the script content are needed or allowed
+
+## Profiling Execution Workflow
+
+After setting up the profiling scripts, follow this execution workflow to profile your Java application and store results in the profiler/results directory:
+
+### Step 1: Create and Make Script Executable
+
+**CRITICAL**: Use the exact script from the template without any changes:
+
+```bash
+# Create the profiler directory structure
+mkdir -p profiler/scripts
+mkdir -p profiler/results
+
+# Copy the EXACT bash script from java-profiling-script-template.md
+# Save it as profiler/scripts/java-profile.sh
+# DO NOT MODIFY THE SCRIPT CONTENT - USE IT EXACTLY AS PROVIDED
+
+# Make the script executable
+chmod +x profiler/scripts/java-profile.sh
+```
+
+**REMINDER**: The script in `java-profiling-script-template.md` is complete and should be copied verbatim. No interpretation, enhancement, or modification is required or allowed.
+
+### Step 2: Execute the Profiling Script
+
+Run the script from your project root directory:
+
+```bash
+# Execute the interactive profiling script
+./profiler/scripts/java-profile.sh
+```
+
+**Expected execution flow:**
+1. **Problem Identification**: The script will first ask you to identify what problem you're trying to solve
+2. **Process Selection**: Lists all Java processes and allows you to select one
+3. **Directory Setup**: Prompts for profiler directory (default: ./profiler)
+4. **Auto-setup**: Downloads and configures async-profiler automatically
+5. **Interactive Menu**: Presents profiling options based on your problem type
+
+### Step 3: Problem-Specific Profiling Commands
+
+Based on the problem you identified, execute these specific profiling commands:
+
+#### For CPU Hotspots and Performance Bottlenecks
+```bash
+# Quick CPU profiling (30 seconds)
+./profiler/current/bin/asprof -d 30 -f ./profiler/results/cpu-hotspots-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Extended CPU profiling with method filtering
+./profiler/current/bin/asprof -d 60 -i 'com/yourpackage/*' -f ./profiler/results/filtered-cpu-$(date +%Y%m%d-%H%M%S).html <PID>
+```
+
+#### For Memory-Related Problems
+```bash
+# Memory allocation profiling
+./profiler/current/bin/asprof -e alloc -d 60 -f ./profiler/results/memory-allocations-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Memory leak detection (longer duration)
+./profiler/current/bin/asprof -e alloc -d 300 --alloc 1m -f ./profiler/results/memory-leak-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Native memory profiling
+./profiler/current/bin/asprof -e native -d 60 -f ./profiler/results/native-memory-$(date +%Y%m%d-%H%M%S).html <PID>
+```
+
+#### For Concurrency and Threading Issues
+```bash
+# Lock contention profiling
+./profiler/current/bin/asprof -e lock -d 60 -f ./profiler/results/lock-contention-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Wall clock profiling (includes waiting threads)
+./profiler/current/bin/asprof -e wall -d 60 -f ./profiler/results/wall-clock-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Thread-specific profiling
+./profiler/current/bin/asprof -d 60 -t -f ./profiler/results/thread-analysis-$(date +%Y%m%d-%H%M%S).html <PID>
+```
+
+#### For Garbage Collection Problems
+```bash
+# GC analysis with JFR
+./profiler/current/bin/asprof -d 120 -o jfr -f ./profiler/results/gc-analysis-$(date +%Y%m%d-%H%M%S).jfr <PID>
+
+# Convert JFR to flamegraph for GC analysis
+./profiler/current/bin/jfr2flame ./profiler/results/gc-analysis-*.jfr ./profiler/results/gc-flamegraph-$(date +%Y%m%d-%H%M%S).html
+```
+
+#### For I/O and Network Bottlenecks
+```bash
+# I/O profiling with wall clock events
+./profiler/current/bin/asprof -e wall -d 90 -f ./profiler/results/io-analysis-$(date +%Y%m%d-%H%M%S).html <PID>
+
+# Combined CPU and I/O analysis
+./profiler/current/bin/asprof -e cpu,wall -d 90 -f ./profiler/results/cpu-io-combined-$(date +%Y%m%d-%H%M%S).html <PID>
+```
+
+### Step 4: Advanced Analysis with Interactive Heatmaps
+
+For time-based analysis, create interactive heatmaps:
+
+```bash
+# Generate JFR recording
+./profiler/current/bin/asprof -d 120 -o jfr -f ./profiler/results/profile-$(date +%Y%m%d-%H%M%S).jfr <PID>
+
+# Convert to interactive heatmap
+./profiler/current/bin/jfrconv --cpu -o heatmap ./profiler/results/profile-*.jfr ./profiler/results/heatmap-cpu-$(date +%Y%m%d-%H%M%S).html
+
+# Create allocation heatmap
+./profiler/current/bin/jfrconv --alloc -o heatmap ./profiler/results/profile-*.jfr ./profiler/results/heatmap-alloc-$(date +%Y%m%d-%H%M%S).html
+```
+
+### Step 5: Results Organization and Analysis
+
+After profiling, organize and analyze your results:
+
+```bash
+# List all generated profiling files
+ls -la ./profiler/results/
+
+# View recent profiling results organized by type
+echo "=== CPU Profiling Results ==="
+ls -lt ./profiler/results/*cpu* ./profiler/results/*flamegraph* 2>/dev/null | head -5
+
+echo "=== Memory Profiling Results ==="
+ls -lt ./profiler/results/*memory* ./profiler/results/*alloc* 2>/dev/null | head -5
+
+echo "=== Threading/Lock Analysis ==="
+ls -lt ./profiler/results/*lock* ./profiler/results/*wall* ./profiler/results/*thread* 2>/dev/null | head -5
+
+echo "=== Heatmap Analysis ==="
+ls -lt ./profiler/results/*heatmap* 2>/dev/null | head -5
+
+echo "=== JFR Recordings ==="
+ls -lt ./profiler/results/*.jfr 2>/dev/null | head -5
+```
+
+## Interpreting Flamegraphs
+
+### Reading Flamegraphs
+- **Width**: Represents the time spent in a method (wider = more time)
+- **Height**: Represents the call stack depth
+- **Color**: Randomly assigned for visibility (no special meaning)
+- **Search**: Use the search box to find specific methods
+- **Zoom**: Click on any frame to zoom in
+
+### Common Patterns to Look For
+- **Wide flames**: Methods consuming significant CPU time
+- **Tall stacks**: Deep call chains that might indicate recursion issues
+- **Flat profiles**: Even distribution might indicate I/O bound operations
+- **Spikes**: Hotspots that are good optimization candidates
+
+## Resources
+
+- [Async-profiler v4.0 Release](mdc:https:/github.com/async-profiler/async-profiler/releases/tag/v4.0)
+- [Async-profiler GitHub Repository](mdc:https:/github.com/async-profiler/async-profiler)
+- [Async-profiler Documentation](mdc:https:/github.com/async-profiler/async-profiler/wiki)
+- [Java Flight Recorder Guide](mdc:https:/docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm)
+- [Brendan Gregg's Flame Graph Resources](mdc:http:/www.brendangregg.com/flamegraphs.html)
+