Repolode
Submit
gaogaotiantian

gaogaotiantian/viztracer

A low-overhead Python tracer that records function calls and visualizes code execution as an interactive timeline.

View on GitHubWebsite
Stars
7,775
Forks
480
Open issues
33
Last commit
last month

What is it?

VizTracer traces Python code execution and displays the result as an interactive timeline in a browser-based viewer built on Perfetto. Each function entry and exit is recorded on the timeline alongside its source code, which makes it useful for debugging unexpected control flow and finding where time is spent.

Most features work without modifying source code: you run a script through the viztracer command, or wrap a section with a VizTracer context manager, and open the generated result.json with vizviewer. It also supports Jupyter cell magics, PyTorch native and GPU event logging, and remote attach to running processes.

Threading, multiprocessing, subprocess, os.fork, concurrent.futures and asyncio are covered, and filters such as minimum duration, stack depth and file include/exclude lists help reduce trace size. It runs on Linux, macOS and Windows, and is installed with pip.

Key features

  • 01Records function entry and exit on a timeline alongside source code.
  • 02Runs scripts, modules and console scripts without changing source code.
  • 03Supports threading, multiprocessing, subprocess, asyncio and PyTorch.
  • 04Offers filters for minimum duration, stack depth and file inclusion or exclusion.
  • 05Can attach to remote running Python processes.
  • 06Works on Linux, macOS and Windows.

Use cases

  • Debugging unexpected control flow in a multithreaded or async Python program.
  • Finding which function calls dominate runtime in a slow script.
  • Inspecting PyTorch model execution including GPU events.
  • Investigating behavior inside a long-running process by attaching to it.

Quick start

  1. 1

    Install VizTracer with pip

    pip install viztracer
  2. 2

    Trace your script from the command line

    viztracer my_script.py arg1 arg2
  3. 3

    Open the generated result.json in the viewer

    vizviewer result.json

In collections

Diagrams, charts & animated visualizationsOpenTelemetry & observability platforms

Topics

#python#profiling#debugging#tracing#visualization#performance#flamegraph#logging#python3#tracer

FAQ

What is viztracer?
A low-overhead Python tracer that records function calls and visualizes code execution as an interactive timeline. VizTracer traces Python code execution and displays the result as an interactive timeline in a browser-based viewer built on Perfetto. Each function entry and exit is recorded on the timeline alongside its source code, which makes it useful for debugging unexpected control flow and finding where time is spent.
Is viztracer free to use? What license does it have?
viztracer is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is viztracer still maintained?
Updated within 6 months. The last commit to viztracer was on Sep 26, 2026.
What can I use viztracer for?
Debugging unexpected control flow in a multithreaded or async Python program. Finding which function calls dominate runtime in a slow script. Inspecting PyTorch model execution including GPU events. Investigating behavior inside a long-running process by attaching to it.
How do I install viztracer?
Install VizTracer with pip: pip install viztracer Trace your script from the command line: viztracer my_script.py arg1 arg2 Open the generated result.json in the viewer: vizviewer result.json
Where can I get viztracer?
The source code and installation instructions are on GitHub: https://github.com/gaogaotiantian/viztracer

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects