VizTracer — Trace and Visualize Python Code Execution

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/