# 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.
[](https://badge.fury.io/py/callflow-tracer)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/callflow-tracer)
[](https://github.com/psf/black)
## ✨ Features
- **Simple API**: Just add `@trace` decorator or use `with trace_scope():`
- **Interactive Visualizations**: Beautiful HTML graphs with zoom, pan, and filtering
- **Performance Insights**: Track execution time, call counts, and bottlenecks
- **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)
```bash
pip install callflow-tracer
```
#### From Source
```bash
git clone https://github.com/rajveer43/callflow-tracer.git
cd callflow-tracer
pip install -e .
```
#### Development Installation
```bash
git clone https://github.com/rajveer43/callflow-tracer.git
cd callflow-tracer
pip install -e ".[dev]"
```
### Basic Usage
#### Option 1: Decorator Approach
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [NetworkX](https://networkx.org/) for graph operations
- Visualizations powered by [vis.js](https://visjs.org/)
- Inspired by the need for better code understanding and debugging tools
## 📞 Support
- 📧 Email: rathodrajveer1311@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/rajveer43/callflow-tracer/issues)
- 📖 Documentation: [GitHub Wiki](https://github.com/rajveer43/callflow-tracer/wiki)
- 💬 Discussions: [GitHub Discussions](https://github.com/rajveer43/callflow-tracer/discussions)
---
**Happy Tracing! 🎉**
*CallFlow Tracer makes understanding your code as easy as `pip install callflow-tracer`*
Raw data
{
"_id": null,
"home_page": "https://github.com/rajveer43/callflow-tracer",
"name": "callflow-tracer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Rajveer Rathod <rathodrajveer1311@gmail.com>",
"keywords": "tracing, profiling, debugging, call-graph, visualization, performance",
"author": "Rajveer Rathod",
"author_email": "Rajveer Rathod <rathodrajveer1311@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fe/b3/c9da72792218f6e7a255b6655c7857adb76245130c5d6e4f7f5a7413d4f6/callflow_tracer-0.1.0.tar.gz",
"platform": null,
"description": "# CallFlow Tracer \ud83e\udde0\r\n\r\nA 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.\r\n\r\n[](https://badge.fury.io/py/callflow-tracer)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://pepy.tech/project/callflow-tracer)\r\n[](https://github.com/psf/black)\r\n\r\n## \u2728 Features\r\n\r\n- **Simple API**: Just add `@trace` decorator or use `with trace_scope():`\r\n- **Interactive Visualizations**: Beautiful HTML graphs with zoom, pan, and filtering\r\n- **Performance Insights**: Track execution time, call counts, and bottlenecks\r\n- **Privacy-Focused**: Optionally anonymize function arguments\r\n- **Multiple Formats**: Export to JSON or interactive HTML\r\n- **Zero Dependencies**: Works out of the box (except for networkx for graph operations)\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n#### From PyPI (Recommended)\r\n```bash\r\npip install callflow-tracer\r\n```\r\n\r\n#### From Source\r\n```bash\r\ngit clone https://github.com/rajveer43/callflow-tracer.git\r\ncd callflow-tracer\r\npip install -e .\r\n```\r\n\r\n#### Development Installation\r\n```bash\r\ngit clone https://github.com/rajveer43/callflow-tracer.git\r\ncd callflow-tracer\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Basic Usage\r\n\r\n#### Option 1: Decorator Approach\r\n```python\r\nfrom callflow_tracer import trace, trace_scope\r\n\r\n@trace\r\ndef calculate_fibonacci(n):\r\n if n <= 1:\r\n return n\r\n return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)\r\n\r\n@trace\r\ndef main():\r\n result = calculate_fibonacci(10)\r\n print(f\"Fibonacci(10) = {result}\")\r\n\r\n# Trace everything and export to HTML\r\nwith trace_scope(\"fibonacci_trace.html\"):\r\n main()\r\n```\r\n\r\n#### Option 2: Context Manager Approach\r\n```python\r\nfrom callflow_tracer import trace_scope\r\n\r\ndef process_data():\r\n data = load_data()\r\n cleaned = clean_data(data)\r\n result = analyze_data(cleaned)\r\n return result\r\n\r\ndef load_data():\r\n return [1, 2, 3, 4, 5]\r\n\r\ndef clean_data(data):\r\n return [x * 2 for x in data if x > 2]\r\n\r\ndef analyze_data(data):\r\n return sum(data) / len(data)\r\n\r\n# Trace the entire process\r\nwith trace_scope(\"data_processing.html\"):\r\n result = process_data()\r\n print(f\"Analysis result: {result}\")\r\n```\r\n\r\n## \ud83d\udcca What You Get\r\n\r\nAfter running your traced code, you'll get an interactive HTML file showing:\r\n\r\n- **Function Nodes**: Each function as a colored node (color indicates performance)\r\n- **Call Relationships**: Arrows showing which functions call which others\r\n- **Performance Metrics**: Hover over nodes to see call counts and timing\r\n- **Interactive Controls**: Filter by module, toggle physics, change layout\r\n- **Statistics**: Total functions, call relationships, and execution time\r\n\r\n## \ud83c\udfaf Advanced Usage\r\n\r\n### Custom Export Options\r\n\r\n```python\r\nfrom callflow_tracer import trace_scope, export_json, export_html\r\n\r\nwith trace_scope() as graph:\r\n # Your code here\r\n my_application()\r\n \r\n# Export to different formats\r\nexport_json(graph, \"trace.json\")\r\nexport_html(graph, \"trace.html\", title=\"My App Call Flow\")\r\n```\r\n\r\n### Selective Tracing\r\n\r\n```python\r\nfrom callflow_tracer import trace\r\n\r\n# Only trace specific functions\r\n@trace\r\ndef critical_function():\r\n # This will be traced\r\n pass\r\n\r\ndef regular_function():\r\n # This won't be traced\r\n pass\r\n\r\n# Use context manager for broader tracing\r\nwith trace_scope(\"selective_trace.html\"):\r\n critical_function() # Traced\r\n regular_function() # Not traced\r\n```\r\n\r\n### Performance Analysis\r\n\r\n```python\r\nfrom callflow_tracer import trace_scope, get_current_graph\r\n\r\nwith trace_scope(\"performance_analysis.html\"):\r\n # Your performance-critical code\r\n optimize_algorithm()\r\n \r\n# Get the graph for programmatic analysis\r\ngraph = get_current_graph()\r\nfor node in graph.nodes.values():\r\n if node.avg_time > 0.1: # Functions taking > 100ms\r\n print(f\"Slow function: {node.full_name} ({node.avg_time:.3f}s avg)\")\r\n```\r\n\r\n## \ud83d\udd27 Configuration\r\n\r\n### HTML Export Options\r\n\r\n```python\r\nfrom callflow_tracer import export_html\r\n\r\n# Customize the HTML output\r\nexport_html(\r\n graph, \r\n \"custom_trace.html\",\r\n title=\"My Custom Title\",\r\n include_vis_js=True # Include vis.js from CDN (requires internet)\r\n)\r\n```\r\n\r\n### Privacy Settings\r\n\r\nThe 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.\r\n\r\n## \ud83d\udcc1 Project Structure\r\n\r\n```\r\ncallflow-tracer/\r\n\u251c\u2500\u2500 callflow_tracer/\r\n\u2502 \u251c\u2500\u2500 __init__.py # Main API\r\n\u2502 \u251c\u2500\u2500 tracer.py # Core tracing logic\r\n\u2502 \u2514\u2500\u2500 exporter.py # JSON/HTML export\r\n\u251c\u2500\u2500 pyproject.toml # Package configuration\r\n\u251c\u2500\u2500 README.md # This file\r\n\u2514\u2500\u2500 LICENSE # MIT License\r\n```\r\n\r\n## \ud83c\udfa8 Visualization Features\r\n\r\nThe generated HTML includes:\r\n\r\n- **Interactive Network**: Zoom, pan, and explore your call graph\r\n- **Color Coding**: \r\n - \ud83d\udd34 Red: Slow functions (>100ms average)\r\n - \ud83d\udfe2 Teal: Medium functions (10-100ms average) \r\n - \ud83d\udd35 Blue: Fast functions (<10ms average)\r\n- **Filtering**: Filter by module to focus on specific parts of your code\r\n- **Layout Options**: Hierarchical or force-directed layouts\r\n- **Physics Controls**: Enable/disable physics simulation\r\n- **Hover Details**: Rich tooltips with performance metrics\r\n\r\n## \ud83d\udea8 Important Notes\r\n\r\n- **Performance Impact**: Tracing adds overhead. Use selectively for production code\r\n- **Thread Safety**: The tracer is thread-safe and can handle concurrent code\r\n- **Memory Usage**: Large applications may generate substantial trace data\r\n- **Privacy**: Function arguments are truncated by default for security\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions 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.\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with [NetworkX](https://networkx.org/) for graph operations\r\n- Visualizations powered by [vis.js](https://visjs.org/)\r\n- Inspired by the need for better code understanding and debugging tools\r\n\r\n## \ud83d\udcde Support\r\n\r\n- \ud83d\udce7 Email: rathodrajveer1311@gmail.com\r\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/rajveer43/callflow-tracer/issues)\r\n- \ud83d\udcd6 Documentation: [GitHub Wiki](https://github.com/rajveer43/callflow-tracer/wiki)\r\n- \ud83d\udcac Discussions: [GitHub Discussions](https://github.com/rajveer43/callflow-tracer/discussions)\r\n\r\n---\r\n\r\n**Happy Tracing! \ud83c\udf89**\r\n\r\n*CallFlow Tracer makes understanding your code as easy as `pip install callflow-tracer`*\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python library for tracing function call relationships and visualizing them as interactive graphs",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/rajveer43/callflow-tracer",
"Issues": "https://github.com/rajveer43/callflow-tracer/issues",
"Repository": "https://github.com/rajveer43/callflow-tracer"
},
"split_keywords": [
"tracing",
" profiling",
" debugging",
" call-graph",
" visualization",
" performance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "95b6b151791b523206e46ed6aef2ea2f6fec9c756115b0967e22ec06c12f0846",
"md5": "fb90e288a723b14d8a8ef306a8ac67cc",
"sha256": "f094e5a3d8509ce24205b3252ff8ed6fdb4d6cc8eb8d21098eb010fe2d0aff35"
},
"downloads": -1,
"filename": "callflow_tracer-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb90e288a723b14d8a8ef306a8ac67cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12529,
"upload_time": "2025-09-16T16:18:38",
"upload_time_iso_8601": "2025-09-16T16:18:38.360184Z",
"url": "https://files.pythonhosted.org/packages/95/b6/b151791b523206e46ed6aef2ea2f6fec9c756115b0967e22ec06c12f0846/callflow_tracer-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "feb3c9da72792218f6e7a255b6655c7857adb76245130c5d6e4f7f5a7413d4f6",
"md5": "17a636cae982b7297e6469809cadd2a3",
"sha256": "f068575b6a3a9739e214425b4e5b8a2dbf852ccca0d5b0ee75430ea389df291e"
},
"downloads": -1,
"filename": "callflow_tracer-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "17a636cae982b7297e6469809cadd2a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16650,
"upload_time": "2025-09-16T16:18:39",
"upload_time_iso_8601": "2025-09-16T16:18:39.807666Z",
"url": "https://files.pythonhosted.org/packages/fe/b3/c9da72792218f6e7a255b6655c7857adb76245130c5d6e4f7f5a7413d4f6/callflow_tracer-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-16 16:18:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rajveer43",
"github_project": "callflow-tracer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "callflow-tracer"
}
JSON
