callflow-tracer 0.2.2

A lightweight Python library for tracing function call relationships and visualizing them as interactive graphs

CallFlow Tracer 🧠

A lightweight Python library for tracing function call relationships and visualizing them as interactive graphs. Perfect for understanding code flow, debugging performance issues, and documenting how your code works.

What's New in 0.2.2 (2025-09-28)

• Stability Fixes in Tracer Core: Hardened error handling in CallTracer._trace_calls, preventing silent failures and ensuring test programs run to completion.
• Decorator/Scope Interop: Resolved conflicts between the @trace decorator and trace_scope context manager; improved caller detection and global state management.
• Improved JSON Export: Fixed "network.getData is not a function" by exporting from original nodes/edges, added richer metadata and better error handling.
• UI Enhancements (HTML Exporter):
  • Added a modern, collapsible CPU profiling section with gradient header and dark code theme.
  • Implemented working module filter with smooth zoom-to-fit and edge filtering.
  • Restored Circular and Timeline layouts with correct positioning and auto-fit behavior.
• Version Sync: Package version aligned across pyproject.toml and callflow_tracer/__init__.py.

Thank you to users for feedback that helped guide these improvements.

✨ Features

• Simple API: Just add @trace decorator or use with trace_scope():
• Interactive Visualizations: Beautiful HTML graphs with zoom, pan, and filtering
• Performance Profiling: Track execution time, memory usage, and bottlenecks
• Detailed Call Analysis: View call hierarchies and timing breakdowns
• Privacy-Focused: Optionally anonymize function arguments
• Multiple Formats: Export to JSON or interactive HTML
• Zero Dependencies: Works out of the box (except for networkx for graph operations)

🚀 Quick Start

Installation

From PyPI (Recommended)

pip install callflow-tracer

From Source

git clone https://github.com/rajveer43/callflow-tracer.git
cd callflow-tracer
pip install -e .

Development Installation

git clone https://github.com/rajveer43/callflow-tracer.git
cd callflow-tracer
pip install -e ".[dev]"

🔍 Advanced Profiling Examples

Memory and Performance Profiling

from callflow_tracer import profile_function, profile_section, get_memory_usage
import time
import random
import numpy as np

@profile_function
def process_data(data_size: int) -> float:
    """Process data with CPU and memory profiling."""
    # Allocate memory
    data = [random.random() for _ in range(data_size)]
    
    # CPU-intensive work
    total = sum(data) / len(data) if data else 0
    
    # Simulate I/O
    time.sleep(0.1)
    
    return total

def analyze_performance():
    """Example using profile_section context manager."""
    with profile_section("Data Processing"):
        # Process different data sizes
        for size in [1000, 10000, 100000]:
            with profile_section(f"Processing {size} elements"):
                result = process_data(size)
                print(f"Result: {result:.4f}")
                
                # Get memory usage
                mem_usage = get_memory_usage()
                print(f"Memory usage: {mem_usage:.2f} MB")

if __name__ == "__main__":
    analyze_performance()
    
    # Export the profile data to HTML
    from callflow_tracer import export_html
    export_html("performance_profile.html")

Visualizing Performance Data

After running the above code, you can view the performance data in an interactive HTML report that includes:

• Call hierarchy with timing information
• Memory usage over time
• Hotspots and bottlenecks
• Function execution statistics

🛠 Basic Usage

Option 1: Decorator Approach

from callflow_tracer import trace, trace_scope

@trace
def calculate_fibonacci(n):
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

@trace
def main():
    result = calculate_fibonacci(10)
    print(f"Fibonacci(10) = {result}")

# Trace everything and export to HTML
with trace_scope("fibonacci_trace.html"):
    main()

Option 2: Context Manager Approach

from callflow_tracer import trace_scope

def process_data():
    data = load_data()
    cleaned = clean_data(data)
    result = analyze_data(cleaned)
    return result

def load_data():
    return [1, 2, 3, 4, 5]

def clean_data(data):
    return [x * 2 for x in data if x > 2]

def analyze_data(data):
    return sum(data) / len(data)

# Trace the entire process
with trace_scope("data_processing.html"):
    result = process_data()
    print(f"Analysis result: {result}")

📊 What You Get

After running your traced code, you'll get an interactive HTML file showing:

• Function Nodes: Each function as a colored node (color indicates performance)
• Call Relationships: Arrows showing which functions call which others
• Performance Metrics: Hover over nodes to see call counts and timing
• Interactive Controls: Filter by module, toggle physics, change layout
• Statistics: Total functions, call relationships, and execution time

🎯 Advanced Usage

Custom Export Options

from callflow_tracer import trace_scope, export_json, export_html

with trace_scope() as graph:
    # Your code here
    my_application()
    
# Export to different formats
export_json(graph, "trace.json")
export_html(graph, "trace.html", title="My App Call Flow")

Selective Tracing

from callflow_tracer import trace

# Only trace specific functions
@trace
def critical_function():
    # This will be traced
    pass

def regular_function():
    # This won't be traced
    pass

# Use context manager for broader tracing
with trace_scope("selective_trace.html"):
    critical_function()  # Traced
    regular_function()   # Not traced

Performance Analysis

from callflow_tracer import trace_scope, get_current_graph

with trace_scope("performance_analysis.html"):
    # Your performance-critical code
    optimize_algorithm()
    
# Get the graph for programmatic analysis
graph = get_current_graph()
for node in graph.nodes.values():
    if node.avg_time > 0.1:  # Functions taking > 100ms
        print(f"Slow function: {node.full_name} ({node.avg_time:.3f}s avg)")

🔧 Configuration

HTML Export Options

from callflow_tracer import export_html

# Customize the HTML output
export_html(
    graph, 
    "custom_trace.html",
    title="My Custom Title",
    include_vis_js=True  # Include vis.js from CDN (requires internet)
)

Privacy Settings

The library automatically truncates function arguments to 100 characters for privacy. For production use, you can modify the CallNode.add_call() method to further anonymize or exclude sensitive data.

📁 Project Structure

callflow-tracer/
├── callflow_tracer/
│   ├── __init__.py          # Main API
│   ├── tracer.py            # Core tracing logic
│   └── exporter.py          # JSON/HTML export
├── pyproject.toml           # Package configuration
├── README.md               # This file
└── LICENSE                 # MIT License

🎨 Visualization Features

The generated HTML includes:

• Interactive Network: Zoom, pan, and explore your call graph
• Color Coding:
  • 🔴 Red: Slow functions (>100ms average)
  • 🟢 Teal: Medium functions (10-100ms average)
  • 🔵 Blue: Fast functions (<10ms average)
• Filtering: Filter by module to focus on specific parts of your code
• Layout Options: Hierarchical or force-directed layouts
• Physics Controls: Enable/disable physics simulation
• Hover Details: Rich tooltips with performance metrics

🚨 Important Notes

• Performance Impact: Tracing adds overhead. Use selectively for production code
• Thread Safety: The tracer is thread-safe and can handle concurrent code
• Memory Usage: Large applications may generate substantial trace data
• Privacy: Function arguments are truncated by default for security

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with NetworkX for graph operations
• Visualizations powered by vis.js
• Inspired by the need for better code understanding and debugging tools

📞 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

---

Happy Tracing! 🎉

CallFlow Tracer makes understanding your code as easy as pip install callflow-tracer