# VizTracer — Trace and Visualize Python Code Execution

> A low-overhead Python tracer that records every function call and renders an interactive timeline for debugging and performance analysis.

## Install

Save as a script file and run:

# VizTracer — Trace and Visualize Python Code Execution

## Quick Use
```bash
pip install viztracer
viztracer my_script.py
vizviewer result.json
# opens an interactive timeline in your browser
```

## Introduction
VizTracer records every function entry and exit in a Python program and produces an interactive Chrome-style trace timeline. It helps developers understand execution flow, find performance bottlenecks, and debug complex concurrency issues by visualizing exactly what happens and when.

## What VizTracer Does
- Records every function call with timestamps and duration
- Generates interactive flame charts viewable in the browser
- Supports multi-process, multi-thread, and async tracing
- Allows custom events and instant markers for domain-specific tracing
- Filters by function name, module, or file to reduce noise

## Architecture Overview
VizTracer hooks into Python's sys.setprofile mechanism using a C extension for minimal overhead. Each function entry and exit is recorded as a trace event with nanosecond timestamps. The trace data is stored in a circular buffer and exported to Chrome Trace Event Format (JSON). The built-in vizviewer launches a local web server using Perfetto UI for interactive exploration.

## Self-Hosting & Configuration
- Install with pip: `pip install viztracer`
- Run directly: `viztracer my_script.py` generates `result.json`
- View traces with `vizviewer result.json` or upload to ui.perfetto.dev
- Filter tracing with `--include_files` or `--exclude_files` patterns
- Set trace buffer size with `--tracer_entries` for long-running programs

## Key Features
- Sub-microsecond overhead per function call via C extension
- Chrome Trace Event Format output compatible with Perfetto and Chrome DevTools
- Multi-process tracing with automatic subprocess follow
- Custom event logging with `VizTracer.log_instant()` and `VizTracer.log_event()`
- Flamegraph generation alongside timeline view

## Comparison with Similar Tools
- **cProfile** — Function-level aggregate stats; VizTracer shows a full execution timeline
- **Pyinstrument** — Statistical sampling with call trees; VizTracer records every call
- **py-spy** — Attaches to running processes; VizTracer instruments from the start
- **Scalene** — Focuses on CPU/memory hotspots; VizTracer focuses on execution flow visualization

## FAQ
**Q: How much overhead does VizTracer add?**
A: Typically 2-5x slowdown, which is low for a tracing profiler that records every function call.

**Q: Can I trace multiprocess applications?**
A: Yes. Use `--log_multiprocess` to automatically trace child processes.

**Q: What viewer should I use?**
A: The built-in `vizviewer` uses Perfetto UI. You can also open trace files in Chrome DevTools.

**Q: Can I add custom trace events?**
A: Yes. Use the `log_instant` and `log_event` APIs to add markers and spans to the timeline.

## Sources
- https://github.com/gaogaotiantian/viztracer
- https://viztracer.readthedocs.io/

---
Source: https://tokrepo.com/en/workflows/asset-5f928744
Author: Script Depot