# StraceTools 🔍
**A modern Python library for parsing, analyzing, and visualizing strace output with ease.**
---
If you find our library useful, please consider starring ⭐ the repository or citing it in your projects! Your support helps us continue improving StraceTools.
## Why StraceTools? 🚀
System debugging and performance analysis often rely on `strace` to understand application behavior. However, existing tools typically fall short:
- **Limited scope**: Most tools only provide basic statistics or file access lists
- **No programmability**: Fixed output formats with no API for custom analysis
- **Poor multi-threading support**: Difficult to analyze concurrent syscall execution
- **No visualization**: Raw text output is hard to interpret for complex applications
**StraceTools bridges these gaps** by providing:
✨ **Comprehensive parsing** with full syscall detail extraction
🔧 **Programmable API** for custom analysis workflows
📊 **Interactive visualizations** for timeline and process analysis
🧵 **Multi-threading support** with process relationship tracking
## Quick Start 🏃♂️
### Getting `strace` Output
To use StraceTools, you first need to generate `strace` output from your application. You can do this by running:
```bash
strace -f -tt -T <other options> -o app_strace.out <your_application>
```
#### Sample Data
You can find some sample strace output in the `examples` directory, they are generated using the following command:
- ls.strace.out: `strace -f -tt -T -s 16 -x -a 40 -o examples/ls.strace.out ls -al /`
### Installation
You can install StraceTools directly from PyPI using pip:
```bash
pip install stracetools
```
### Basic Usage
```python
from stracetools import StraceParser, StraceAnalyzer
# Parse strace output
parser = StraceParser()
events = parser.parse_file("app_strace.out")
# Analyze the results
analyzer = StraceAnalyzer(events)
# Quick insights
print(f"Processes: {len(analyzer.get_pids())}")
print(f"Syscalls: {len(analyzer.get_syscall_names())}")
print(f"Duration: {analyzer.events[-1].timestamp - analyzer.events[0].timestamp}")
# Brief overview
print(analyzer.summary())
```
## Roadmap 🗺️
### Current Status ✅
- [x] Complete strace parsing with multi-threading support
- [x] Comprehensive filtering and analysis API
- [x] Rich statistics and insights
- [x] Interactive timeline Gantt charts
- [x] Process activity visualization
### Coming Soon 🚧
- [ ] **Lazy, chainable query** interface
- [ ] **Official publication** on PyPI
- [ ] **Export to CSV/JSON** for further analysis
- [ ] **Enhance processing speed** for large strace files
- [ ] **Complete visualization suite** (frequency charts, duration histograms)
- [ ] **Integration with profiling tools**
## Requirements 📋
- **Python 3.8+**
- **Core dependencies**: None (pure Python)
- **Visualization** (optional): `matplotlib>=3.5`, `plotly>=5.0`, `numpy>=1.20`
## Contributing 🤝
We welcome contributions! Whether it's:
- 🐛 **Bug reports** and feature requests
- 📖 **Documentation** improvements
- 🔧 **Code contributions** (parsing improvements, new analysis methods)
- 📊 **Visualization enhancements**
## Key Features 🛠️
### 🎯 **Easy Parsing**
```python
# Initialize parser
parser = StraceParser()
# Parse strace output from a string
event = parser.parse_string("52806 11:11:17.955673 nanosleep({tv_sec=0, tv_nsec=20000}, NULL) = 0 <0.000102>")
# Parse strace output file
events = parser.parse_file("app_strace.out")
```
### 🔍 **Powerful Filtering & Analysis**
```python
# Initialize analyzer with parsed events
analyzer = StraceAnalyzer(events)
# Get all PIDs
pids = analyzer.get_pids()
# Filter by process
events_1234 = analyzer.filter_by_pid(1234)
# Get all syscall names
syscall_names = analyzer.get_syscall_names()
# Filter by syscall with argument matching
file_reads = analyzer.filter_by_syscall("read", args=["file.txt"])
# Filter by event type of signals
signal_events = analyzer.filter_by_event_type(TraceEventType.SIGNAL)
# Time-based filtering
recent_events = analyzer.filter_by_time_range(start_time, end_time)
# Performance analysis
error_calls = analyzer.filter_with_errors()
slow_calls = analyzer.filter_slow_calls(0.01) # > 10ms
```
### 📊 **Rich Statistics**
```python
# Process information
process_info = analyzer.get_process_info(1234)
print(f"Runtime: {process_info.last_seen - process_info.first_seen}")
print(f"Syscalls: {process_info.syscall_count}")
print(f"CPU time: {process_info.total_duration:.3f}s")
# Syscall statistics
read_stats = analyzer.get_syscall_stats("read")
print(f"Average read duration: {read_stats.avg_duration:.6f}s")
print(f"Error rate: {read_stats.error_count / read_stats.count:.1%}")
# Top syscalls by frequency or duration
top_frequent = analyzer.get_top_syscalls(10, by='count')
top_expensive = analyzer.get_top_syscalls(10, by='duration')
# File operations analysis
file_ops = analyzer.get_file_operations(filename_pattern=r"\.log$")
# Network operations
network_ops = analyzer.get_network_operations()
# Timeline analysis
timeline = analyzer.get_timeline_summary(bucket_size=timedelta(seconds=1))
```
### 📈 **Interactive Visualizations** *(Partial - In Progress)*
```python
visualizer = StraceVisualizer(analyzer, color_map_file="default_colors.json", auto_fillup=False)
# Interactive Gantt chart timeline
gantt_fig = visualizer.plot_timeline_gantt(
pids=[1234, 5678], # Filter specific processes
syscalls=["read", "write"], # Filter specific syscalls
max_events=4000, # Limit for performance
)
gantt_fig.write_html("gantt.html")
# Process activity timeline
activity_fig = visualizer.plot_process_activity()
activity_fig.show()
```
<img alt="Gantt Chart Example" height="500" src="./docs/filtered_events.svg"/>
## License 📄
MIT License - see [LICENSE](LICENSE) file for details.
---
## Acknowledgments 🙏
Built for developers and system administrators who need deeper insights into application behavior.
Inspired by the need for modern, programmable strace analysis tools.
If you find our library useful, please consider starring ⭐ the repository and citing it in your projects!
Your support helps us continue improving StraceTools.
Raw data
{
"_id": null,
"home_page": null,
"name": "stracetools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "strace, system calls, debugging, performance analysis, linux",
"author": null,
"author_email": "Alex Jiakai Xu <jiakai.xu@columbia.edu>",
"download_url": "https://files.pythonhosted.org/packages/f3/cb/6f8b49144ad01145fd0eab2f92a81bd8912108cbb536e09d31182165f720/stracetools-0.1.0.tar.gz",
"platform": null,
"description": "# StraceTools \ud83d\udd0d\n\n**A modern Python library for parsing, analyzing, and visualizing strace output with ease.**\n\n---\n\nIf you find our library useful, please consider starring \u2b50 the repository or citing it in your projects! Your support helps us continue improving StraceTools.\n\n\n## Why StraceTools? \ud83d\ude80\n\nSystem debugging and performance analysis often rely on `strace` to understand application behavior. However, existing tools typically fall short:\n\n- **Limited scope**: Most tools only provide basic statistics or file access lists\n- **No programmability**: Fixed output formats with no API for custom analysis\n- **Poor multi-threading support**: Difficult to analyze concurrent syscall execution\n- **No visualization**: Raw text output is hard to interpret for complex applications\n\n**StraceTools bridges these gaps** by providing:\n\n\u2728 **Comprehensive parsing** with full syscall detail extraction \n\ud83d\udd27 **Programmable API** for custom analysis workflows \n\ud83d\udcca **Interactive visualizations** for timeline and process analysis \n\ud83e\uddf5 **Multi-threading support** with process relationship tracking \n\n## Quick Start \ud83c\udfc3\u200d\u2642\ufe0f\n\n### Getting `strace` Output\nTo use StraceTools, you first need to generate `strace` output from your application. You can do this by running:\n\n```bash\nstrace -f -tt -T <other options> -o app_strace.out <your_application>\n```\n\n#### Sample Data\nYou can find some sample strace output in the `examples` directory, they are generated using the following command:\n- ls.strace.out: `strace -f -tt -T -s 16 -x -a 40 -o examples/ls.strace.out ls -al /`\n\n\n### Installation\nYou can install StraceTools directly from PyPI using pip:\n```bash\npip install stracetools\n```\n\n### Basic Usage\n\n```python\nfrom stracetools import StraceParser, StraceAnalyzer\n\n# Parse strace output\nparser = StraceParser()\nevents = parser.parse_file(\"app_strace.out\")\n\n# Analyze the results\nanalyzer = StraceAnalyzer(events)\n\n# Quick insights\nprint(f\"Processes: {len(analyzer.get_pids())}\")\nprint(f\"Syscalls: {len(analyzer.get_syscall_names())}\")\nprint(f\"Duration: {analyzer.events[-1].timestamp - analyzer.events[0].timestamp}\")\n\n# Brief overview\nprint(analyzer.summary())\n```\n\n## Roadmap \ud83d\uddfa\ufe0f\n\n### Current Status \u2705\n- [x] Complete strace parsing with multi-threading support\n- [x] Comprehensive filtering and analysis API\n- [x] Rich statistics and insights\n- [x] Interactive timeline Gantt charts\n- [x] Process activity visualization\n\n### Coming Soon \ud83d\udea7\n- [ ] **Lazy, chainable query** interface\n- [ ] **Official publication** on PyPI\n- [ ] **Export to CSV/JSON** for further analysis\n- [ ] **Enhance processing speed** for large strace files\n- [ ] **Complete visualization suite** (frequency charts, duration histograms)\n- [ ] **Integration with profiling tools**\n\n## Requirements \ud83d\udccb\n\n- **Python 3.8+**\n- **Core dependencies**: None (pure Python)\n- **Visualization** (optional): `matplotlib>=3.5`, `plotly>=5.0`, `numpy>=1.20`\n\n## Contributing \ud83e\udd1d\n\nWe welcome contributions! Whether it's:\n\n- \ud83d\udc1b **Bug reports** and feature requests\n- \ud83d\udcd6 **Documentation** improvements \n- \ud83d\udd27 **Code contributions** (parsing improvements, new analysis methods)\n- \ud83d\udcca **Visualization enhancements**\n\n\n## Key Features \ud83d\udee0\ufe0f\n\n### \ud83c\udfaf **Easy Parsing**\n\n```python\n# Initialize parser\nparser = StraceParser()\n\n# Parse strace output from a string\nevent = parser.parse_string(\"52806 11:11:17.955673 nanosleep({tv_sec=0, tv_nsec=20000}, NULL) = 0 <0.000102>\")\n\n# Parse strace output file\nevents = parser.parse_file(\"app_strace.out\")\n\n```\n\n### \ud83d\udd0d **Powerful Filtering & Analysis**\n\n```python\n# Initialize analyzer with parsed events\nanalyzer = StraceAnalyzer(events)\n\n# Get all PIDs\npids = analyzer.get_pids()\n\n# Filter by process\nevents_1234 = analyzer.filter_by_pid(1234)\n\n# Get all syscall names\nsyscall_names = analyzer.get_syscall_names()\n\n# Filter by syscall with argument matching\nfile_reads = analyzer.filter_by_syscall(\"read\", args=[\"file.txt\"])\n\n# Filter by event type of signals\nsignal_events = analyzer.filter_by_event_type(TraceEventType.SIGNAL)\n\n# Time-based filtering\nrecent_events = analyzer.filter_by_time_range(start_time, end_time)\n\n# Performance analysis\nerror_calls = analyzer.filter_with_errors()\nslow_calls = analyzer.filter_slow_calls(0.01) # > 10ms\n```\n\n### \ud83d\udcca **Rich Statistics**\n\n```python\n# Process information\nprocess_info = analyzer.get_process_info(1234)\nprint(f\"Runtime: {process_info.last_seen - process_info.first_seen}\")\nprint(f\"Syscalls: {process_info.syscall_count}\")\nprint(f\"CPU time: {process_info.total_duration:.3f}s\")\n\n# Syscall statistics\nread_stats = analyzer.get_syscall_stats(\"read\")\nprint(f\"Average read duration: {read_stats.avg_duration:.6f}s\")\nprint(f\"Error rate: {read_stats.error_count / read_stats.count:.1%}\")\n\n# Top syscalls by frequency or duration\ntop_frequent = analyzer.get_top_syscalls(10, by='count')\ntop_expensive = analyzer.get_top_syscalls(10, by='duration')\n\n# File operations analysis\nfile_ops = analyzer.get_file_operations(filename_pattern=r\"\\.log$\")\n\n# Network operations\nnetwork_ops = analyzer.get_network_operations()\n\n# Timeline analysis\ntimeline = analyzer.get_timeline_summary(bucket_size=timedelta(seconds=1))\n```\n\n### \ud83d\udcc8 **Interactive Visualizations** *(Partial - In Progress)*\n\n```python\nvisualizer = StraceVisualizer(analyzer, color_map_file=\"default_colors.json\", auto_fillup=False)\n\n# Interactive Gantt chart timeline\ngantt_fig = visualizer.plot_timeline_gantt(\n pids=[1234, 5678], # Filter specific processes\n syscalls=[\"read\", \"write\"], # Filter specific syscalls\n max_events=4000, # Limit for performance\n)\ngantt_fig.write_html(\"gantt.html\")\n\n# Process activity timeline \nactivity_fig = visualizer.plot_process_activity()\nactivity_fig.show()\n```\n\n<img alt=\"Gantt Chart Example\" height=\"500\" src=\"./docs/filtered_events.svg\"/>\n\n\n## License \ud83d\udcc4\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## Acknowledgments \ud83d\ude4f\n\nBuilt for developers and system administrators who need deeper insights into application behavior.\nInspired by the need for modern, programmable strace analysis tools.\n\nIf you find our library useful, please consider starring \u2b50 the repository and citing it in your projects!\nYour support helps us continue improving StraceTools.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for parsing and analyzing strace output",
"version": "0.1.0",
"project_urls": {
"Repository": "https://github.com/Alex-XJK/stracetools"
},
"split_keywords": [
"strace",
" system calls",
" debugging",
" performance analysis",
" linux"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f464930e54f00b528ef24f7cffd44498c11b1fc0486a85bac137a6072a2be0c",
"md5": "df423189e7122555ba3158037c78370a",
"sha256": "6eaa4cd644c118a1401038311b15d1462151890ff06eba98735226132f4aae72"
},
"downloads": -1,
"filename": "stracetools-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df423189e7122555ba3158037c78370a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17767,
"upload_time": "2025-08-02T18:18:41",
"upload_time_iso_8601": "2025-08-02T18:18:41.707234Z",
"url": "https://files.pythonhosted.org/packages/8f/46/4930e54f00b528ef24f7cffd44498c11b1fc0486a85bac137a6072a2be0c/stracetools-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f3cb6f8b49144ad01145fd0eab2f92a81bd8912108cbb536e09d31182165f720",
"md5": "a3095fee1e599c9c6237b97c4329b21e",
"sha256": "2f412bdd5d75f0659d10cfb773f8c47e6961520a654c7feba50a3d7ea4133df1"
},
"downloads": -1,
"filename": "stracetools-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a3095fee1e599c9c6237b97c4329b21e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 350784,
"upload_time": "2025-08-02T18:18:43",
"upload_time_iso_8601": "2025-08-02T18:18:43.159741Z",
"url": "https://files.pythonhosted.org/packages/f3/cb/6f8b49144ad01145fd0eab2f92a81bd8912108cbb536e09d31182165f720/stracetools-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 18:18:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Alex-XJK",
"github_project": "stracetools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "setuptools",
"specs": [
[
"~=",
"80.3.1"
]
]
},
{
"name": "plotly",
"specs": [
[
"~=",
"6.2.0"
]
]
}
],
"lcname": "stracetools"
}
JSON
