🦀 Ferric

LLM-friendly flamegraph analysis tool with comprehensive statistical analysis and performance health assessment.

Developer note: I made this project over the course of 48 hours as a way of learning how to optimally pair program with an LLM, in my case I was using Claude Code. Really happy with these results but of course there's more testing I'll need to do but as I run this on more complex code doing more performant tasks I'll make changes to this tool. There were some very interesting use cases for this kind of tool, having something that presents results in a LLM efficent way has some interesting consequences.

✨ Features

• 🤖 LLM-Friendly Output: Structured JSON with comprehensive performance metrics
• 📊 Statistical Analysis: CPU distribution, concentration metrics, and performance health assessment
• 🎯 Performance Tiers: Automatic categorization into critical, high, medium, low, and minimal tiers
• 🧮 Mathematical Accuracy: Robust statistical calculations with outlier-resistant algorithms
• 📈 Comparison Analysis: Before/after performance analysis with detailed delta calculations
• 🗂️ Call Tree Visualization: Pretty-printed flamegraph structure with CPU attribution

🚀 Quick Start

Installation

cargo install ferric-ai

# Or from source
git clone https://github.com/dolly-parseton/ferric.git
cd ferric
cargo build --release

Workflow: LLM Coding Assistants

• Structured analysis: JSON output perfect for LLM processing
• Statistical insights: Comprehensive performance health assessment
• Comparison analysis: Before/after optimization tracking
• Mathematical accuracy: Robust calculations with fixed precision issues

Below is the current functionality. I suggest using an LLM-backed coding assistant like Claude Code to run ferric and analyze the results - the structured output is designed for AI interpretation.

# 1. Basic flamegraph analysis
ferric -f app.svg stats summary --json

# 2. Identify performance hotspots
ferric -f app.svg stats hotspots --json

# 3. Get optimization recommendations
ferric -f app.svg stats diagnosis --json

# 4. Analyze statistical distribution
ferric -f app.svg stats distribution --json

# 5. Complete analysis (all metrics)
ferric -f app.svg stats comprehensive --json

# 6. Compare before/after performance
ferric -f before.svg -c after.svg stats comprehensive --json

🔍 Commands Overview

📊 Stats Analysis (Primary Interface)

All stats subcommands support --json for structured output and -c/--compare for before/after analysis.

# Basic flamegraph inventory
ferric -f app.svg stats summary [--json]

# CPU concentration analysis and performance tiers
ferric -f app.svg stats hotspots [--json]

# Health assessment and optimization recommendations
ferric -f app.svg stats diagnosis [--json]

# Statistical distribution patterns and variability analysis
ferric -f app.svg stats distribution [--json]

# Complete analysis combining all metrics
ferric -f app.svg stats comprehensive [--json]

# Comparison analysis (before vs after)
ferric -f before.svg -c after.svg stats [subcommand] [--json]

🗂️ Visualization

# Pretty-print flamegraph as formatted call tree
ferric -f app.svg pretty-print

# LLM guidance and documentation
ferric -f app.svg llm-guide

📊 Sample Output

Hotspots Analysis (JSON)

{
  "filename": "app.svg",
  "basic_stats": {
    "total_functions": 33,
    "root_functions": 2,
    "leaf_functions": 3,
    "max_depth": 25,
    "total_cpu_percent": 100.0,
    "total_samples": 35280497
  },
  "concentration_metrics": {
    "top_1_cpu": 54.426,
    "top_3_cpu": 99.976,
    "top_5_cpu": 100.0,
    "top_10_cpu": 100.0,
    "gini_coefficient": 0.701,
    "efficiency_ratio": 0.333
  },
  "performance_tiers": {
    "critical": [["main", 54.426], ["fib_recursive", 11.670]],
    "high": [],
    "medium": [],
    "low": [["[ld-linux-x86-64.so.2]", 0.656]],
    "minimal": [["[unknown]", 0.024]],
    "zero_count": 22
  }
}

Comprehensive Analysis (JSON)

{
  "filename": "app.svg",
  "analysis_results": {
    "basic": {
      "total_functions": 33,
      "max_depth": 25,
      "total_samples": 35280497
    },
    "concentration": {
      "top_1_cpu": 54.426,
      "gini_coefficient": 0.701
    },
    "statistical_shape": {
      "skewness": 2.660,
      "kurtosis": 7.806,
      "coefficient_of_variation": 175.829,
      "spread_ratio": 106.300,
      "percentiles": {
        "p10": 0.0002,
        "p25": 0.025,
        "p50": 0.656,
        "p75": 11.212,
        "p90": 11.670
      }
    },
    "health": {
      "hotspot_severity": "Critical",
      "work_distribution": "Critical",
      "optimization_priority": "Critical",
      "recommended_action": "Focus on optimizing top function for 54.4% improvement potential"
    }
  }
}

🎯 LLM Integration Guide

The best approach is to ask your LLM coding assistant to run ferric commands directly. The tool provides comprehensive help text and structured JSON output designed for AI interpretation.

Key Integration Points

1. Structured JSON Output: Consistent schema across all subcommands
2. Statistical Analysis: Mathematical rigor with outlier-resistant algorithms
3. Performance Health Assessment: Automated optimization recommendations
4. Comparison Analysis: Before/after performance tracking with delta calculations
5. Comprehensive Metadata: Rich context for informed AI recommendations

Recommended LLM Workflow

# Phase 1: Initial Assessment
ferric -f app.svg stats summary --json

# Phase 2: Identify Bottlenecks
ferric -f app.svg stats hotspots --json

# Phase 3: Get Recommendations
ferric -f app.svg stats diagnosis --json

# Phase 4: Statistical Analysis
ferric -f app.svg stats distribution --json

# Phase 5: Compare Improvements
ferric -f before.svg -c after.svg stats comprehensive --json

Integration Benefits

• Mathematical Accuracy: Fixed precision issues, no >100% CPU values
• Robust Statistics: IQR-based spread ratios, coefficient of variation as percentages
• Consistent Output: All subcommands use identical JSON schema patterns
• Performance Tiers: Automatic categorization into actionable severity levels
• Health Metrics: Clear optimization priority and recommended actions

📈 Analysis Capabilities

Statistical Metrics

• CPU Concentration: Top 1/3/5/10 function analysis with Gini coefficient
• Distribution Analysis: Skewness, kurtosis, coefficient of variation, percentiles
• Performance Tiers: Automatic categorization (critical >10%, high 5-10%, etc.)
• Health Assessment: Optimization priority and specific recommendations
• Spread Analysis: Robust IQR-based ratios resistant to outliers

Comparison Analysis

• Before/After Tracking: Detailed delta calculations with percentage changes
• Performance Regression Detection: Automatic identification of improvements/degradations
• Statistical Significance: Change magnitude assessment with color-coded indicators
• Comprehensive Deltas: Function count, depth, sample count, and tier changes

🏗️ Architecture Highlights

Dependency Optimization

• Minimal footprint: Essential dependencies only (clap, serde, quick-xml, regex, chrono, uuid, glob)
• Fast compilation: No heavy async or web dependencies
• Custom error handling: Purpose-built FerricError enum with comprehensive error context
• Efficient XML parsing: Fast SVG processing with quick-xml

Key Components

Design Philosophy

• Mathematical Rigor: Accurate calculations with fixed precision issues
• LLM-First: Structured JSON output designed for AI interpretation
• Statistical Robustness: Outlier-resistant algorithms (IQR vs max/min)
• Performance Health: Automated assessment and optimization recommendations

🧪 Tested & Validated

Mathematical Accuracy:

• ✅ Fixed >100% CPU bug: Accurate total_samples calculation from root nodes
• ✅ Robust spread ratios: IQR-based (1-50x) instead of extreme max/min (30,000x+)
• ✅ Eliminated negative zero: Fixed -0.0% display issues in comparisons
• ✅ Statistical validity: Outlier-resistant algorithms with proper quartile calculations

Real-World Testing:

• ✅ Complex recursion: 26-level fibonacci analysis with 35M+ samples
• ✅ Large datasets: Memory allocator profiles with 434M+ samples, 65+ functions
• ✅ Diverse workloads: I/O-heavy, CPU-bound, string processing, JSON parsing
• ✅ Comparison analysis: Before/after optimization tracking

Production Ready:

• ✅ Mathematical rigor: All CPU calculations bounded ≤100%
• ✅ Comprehensive JSON: All 5 subcommands support structured output
• ✅ Consistent schema: LLM-friendly output patterns
• ✅ Error handling: Robust parsing with comprehensive error context

🔧 Development

Build Requirements

# Rust 2021 edition
cargo build --release
cargo test
cargo clippy --all-targets

Architecture Overview

src/
├── cli/                # Clap-based CLI with stats subcommands
├── parser/             # SVG flamegraph parser with tree structures
├── commands/           # Command handlers and analysis logic
│   └── stats/          # Statistics analysis subcommands
│       ├── calculations/   # Mathematical operations
│       ├── subcommands/    # Individual stats handlers
│       └── display/        # Output formatting
├── helpers.rs          # Utility functions and comparison helpers
├── handler.rs          # Command routing and execution
├── error.rs            # Custom error types
└── main.rs             # CLI dispatch and initialization

📄 License

Licensed under the MIT License. See LICENSE for details.

🙏 Acknowledgments

Dependencies:

• clap - CLI framework with derive support
• quick-xml - Fast XML/SVG parsing
• serde - JSON serialization framework
• regex - Pattern matching engine
• chrono - Date/time handling
• uuid - Unique identifier generation
• glob - File pattern matching

Inspiration:

• Brendan Gregg's FlameGraph - Original flamegraph concept
• Statistical analysis tools and APM platforms for robust algorithms