Comprehensive guide to all features developed in the CallFlow Tracer package.

📋 Table of Contents

  1. Core Features
  2. Visualization Features
  3. Profiling Features
  4. Flamegraph Features
  5. Jupyter Integration
  6. Export Features
  7. UI/UX Features
  8. Recent Fixes

Core Features

1. Function Call Tracing

Description: Automatically trace function calls and build a call graph.

Methods:

Features:

Example:

from callflow_tracer import trace_scope

with trace_scope() as graph:
    my_application()

print(f"Traced {len(graph.nodes)} functions")
print(f"Found {len(graph.edges)} call relationships")

Use Cases:

2. Call Graph Analysis

Description: Programmatic access to call graph data.

Features:

Example:

with trace_scope() as graph:
    my_function()

# Analyze nodes
for node in graph.nodes.values():
    print(f"{node.full_name}:")
    print(f"  Calls: {node.call_count}")
    print(f"  Total time: {node.total_time:.4f}s")
    print(f"  Avg time: {node.avg_time:.4f}s")

# Find bottlenecks
bottlenecks = [n for n in graph.nodes.values() if n.avg_time > 0.1]
print(f"Found {len(bottlenecks)} slow functions")

Use Cases:

Visualization Features

1. Interactive Call Graph

Description: Beautiful HTML visualization of function calls.

Features:

Color Coding:

Example:

from callflow_tracer import trace_scope, export_html

with trace_scope() as graph:
    my_application()

export_html(graph, "callgraph.html", title="My App Call Graph")

Use Cases:

2. Multiple Layout Options

Description: Different ways to visualize the call graph.

Layouts:

Hierarchical

Force-Directed

Circular

Timeline

Example:

export_html(graph, "hierarchical.html", layout="hierarchical")
export_html(graph, "force.html", layout="force")
export_html(graph, "circular.html", layout="circular")
export_html(graph, "timeline.html", layout="timeline")

Use Cases:

3. Module Filtering

Description: Filter the graph by Python module.

Features:

How It Works:

  1. Open HTML file
  2. Use “Filter by Module” dropdown
  3. Select a module
  4. Graph automatically filters and zooms

Use Cases:

Profiling Features

1. CPU Profiling (cProfile Integration)

Description: Detailed CPU performance profiling.

Features:

Metrics Captured:

Example:

from callflow_tracer import profile_section

with profile_section("My Code") as stats:
    expensive_function()

# Access CPU stats
cpu_stats = stats._get_cpu_stats()
print(cpu_stats['profile_data'])

Use Cases:

2. Memory Profiling

Description: Track memory usage during execution.

Features:

Metrics Captured:

Example:

from callflow_tracer import profile_function, get_memory_usage

@profile_function
def memory_intensive():
    data = [i for i in range(1000000)]
    return data

result = memory_intensive()
stats = memory_intensive.performance_stats

mem_stats = stats._get_memory_stats()
print(f"Current: {mem_stats['current_mb']:.2f}MB")
print(f"Peak: {mem_stats['peak_mb']:.2f}MB")

Use Cases:

3. I/O Wait Time Tracking

Description: Measure time spent waiting for I/O operations.

Features:

How It Works:

Example:

from callflow_tracer import profile_section
import time

with profile_section("I/O Operations") as stats:
    time.sleep(0.1)  # Simulates I/O
    compute()        # CPU work

stats_dict = stats.to_dict()
print(f"I/O wait: {stats_dict['io_wait']:.4f}s")

Use Cases:

4. Combined Profiling

Description: Combine all profiling metrics.

Features:

Example:

from callflow_tracer import trace_scope, profile_section, export_html

with profile_section("Complete Analysis") as perf_stats:
    with trace_scope() as graph:
        my_application()

# Export with all profiling data
export_html(
    graph,
    "complete_analysis.html",
    profiling_stats=perf_stats.to_dict()
)

Use Cases:

Flamegraph Features

1. Basic Flamegraph

Description: Stacked bar chart showing call hierarchy and time.

Features:

Example:

from callflow_tracer import trace_scope
from callflow_tracer.flamegraph import generate_flamegraph

with trace_scope() as graph:
    my_application()

generate_flamegraph(graph, "flamegraph.html")

Use Cases:

2. Enhanced Flamegraph (NEW!)

Description: Advanced flamegraph with statistics and search.

Features:

Statistics Panel Shows:

Example:

generate_flamegraph(
    graph,
    "enhanced.html",
    title="Performance Analysis",
    color_scheme="performance",  # Green=fast, Red=slow
    show_stats=True,
    search_enabled=True,
    min_width=0.1,
    width=1600,
    height=1000
)

Use Cases:

3. Color Schemes

Description: 5 different color schemes for different needs.

Available Schemes:

Default

Hot 🔥

Cool ❄️

Rainbow 🌈

Performance ⚡ (RECOMMENDED!)

Example:

# Try each scheme
for scheme in ['default', 'hot', 'cool', 'rainbow', 'performance']:
    generate_flamegraph(
        graph,
        f"flamegraph_{scheme}.html",
        color_scheme=scheme
    )

Use Cases:

4. Search Functionality

Description: Find specific functions in large flamegraphs.

Features:

How to Use:

  1. Open flamegraph HTML
  2. Type function name in search box
  3. Press Enter or wait
  4. Matching functions highlighted
  5. Click “Clear” to reset

Example:

generate_flamegraph(
    graph,
    "searchable.html",
    search_enabled=True
)
# Then search for: "database", "api", "process", etc.

Use Cases:

5. SVG Export

Description: Export flamegraph as high-quality vector graphics.

Features:

How to Use:

  1. Open flamegraph HTML
  2. Click “💾 Export SVG” button
  3. File downloads automatically
  4. Use in presentations/reports

Use Cases:

Jupyter Integration

1. Magic Commands

Description: IPython magic commands for quick tracing.

Commands:

%callflow_trace (Line Magic)

Trace a single line of code.

%callflow_trace my_function()

%%callflow_cell_trace (Cell Magic)

Trace an entire cell.

%%callflow_cell_trace

def my_function():
    return 42

result = my_function()
print(result)

Use Cases:

2. Inline Visualization

Description: Display interactive graphs directly in notebooks.

Features:

Example:

from callflow_tracer import trace_scope
from callflow_tracer.jupyter import display_callgraph

with trace_scope() as graph:
    my_function()

# Display inline
display_callgraph(
    graph.to_dict(),
    width="100%",
    height="800px",
    layout="force"
)

Use Cases:

3. Full Feature Support

Description: All features work in Jupyter.

Supported:

Example:

# Complete workflow in Jupyter
with profile_section("Analysis") as stats:
    with trace_scope() as graph:
        ml_pipeline()

# Display graph
display_callgraph(graph.to_dict())

# Show stats
print(stats.to_dict())

# Export
export_html(graph, "analysis.html", profiling_stats=stats.to_dict())
generate_flamegraph(graph, "flamegraph.html", color_scheme="performance")

Use Cases:

Export Features

1. HTML Export

Description: Export to interactive HTML files.

Features:

Options:

export_html(
    graph,
    "output.html",
    title="Custom Title",
    layout="hierarchical",  # or 'force', 'circular', 'timeline'
    profiling_stats=stats_dict
)

Generated Files Include:

Use Cases:

2. JSON Export

Description: Export graph data as JSON.

Features:

Format:

{
  "metadata": {
    "total_nodes": 10,
    "total_edges": 15,
    "duration": 1.234,
    "export_timestamp": "2025-10-05T...",
    "version": "callflow-tracer",
    "title": "My Graph"
  },
  "nodes": [...],
  "edges": [...]
}

Example:

from callflow_tracer import export_json

export_json(graph, "trace.json")

# Load and analyze
import json
with open("trace.json") as f:
    data = json.load(f)

print(f"Nodes: {data['metadata']['total_nodes']}")

Use Cases:

3. SVG Export (Flamegraph)

Description: Export flamegraphs as vector graphics.

Features:

Use Cases:

UI/UX Features

1. Modern Design

Features:

Elements:

2. Responsive Design

Features:

Breakpoints:

3. Interactive Controls

Features:

All Controls:

4. Rich Tooltips

Features:

Tooltip Shows:

Recent Fixes

1. CPU Profiling Fix

Problem: CPU profile always showed 0.000s execution time.

Solution:

Impact: ✅ Working CPU profiling with accurate data

2. Module Filter Fix

Problem: Module filter dropdown had no functionality.

Solution:

Impact: ✅ Working module filtering

3. Layout Fixes

Problem: Circular and Timeline layouts didn’t work.

Solution:

Impact: ✅ All 4 layouts working correctly

4. JSON Export Fix

Problem: “network.getData is not a function” error.

Solution:

Impact: ✅ Working JSON export

5. Tracer Stability Fix

Problem: Programs stopped executing after first few print statements.

Solution:

Impact: ✅ Stable tracing, programs run to completion

Feature Matrix

Feature Status Version
Call Tracing ✅ 0.1.0
Call Graph Viz ✅ 0.1.0
JSON Export ✅ Fixed 0.2.2
HTML Export ✅ 0.1.0
CPU Profiling ✅ Fixed Latest
Memory Profiling ✅ 0.2.0
I/O Tracking ✅ 0.2.0
Flamegraph ✅ 0.2.0
Enhanced Flamegraph ✅ New! Latest
Statistics Panel ✅ New! Latest
Search ✅ New! Latest
5 Color Schemes ✅ New! Latest
SVG Export ✅ New! Latest
Module Filter ✅ Fixed Latest
All Layouts ✅ Fixed Latest
Jupyter Integration ✅ New! Latest
Magic Commands ✅ New! Latest
Inline Display ✅ New! Latest
Modern UI ✅ New! Latest
Responsive Design ✅ New! Latest

Summary

CallFlow Tracer now includes:

✅ Core Features

✅ Visualization

✅ Profiling

✅ Flamegraphs

✅ Jupyter

✅ Export

✅ UI/UX

Features Documentation - Last Updated: 2025-10-05