DOCSEARCHbyAlgolia
Submit Docs

VizTracer Documentation

repository·master·Indexed 27 days ago

https://github.com/gaogaotiantian/viztracer

A low-overhead logging, debugging, and profiling tool for tracing and visualizing Python code execution using a Perfetto-powered front-end. It supports CLI usage, inline integration via the VizTracer class, and Jupyter Notebook cell magics. Key features include native asyncio support, PyTorch native call and GPU event logging, and compatibility with multi-threading, multiprocessing, subprocesses, and loky. Includes vizviewer for visualizing trace reports and utilities for combining, compressing, and aligning JSON reports.

Tokens
12.2K
Snippets
45
Records
93
Agent score
93%

What's inside viztracer

  1. Manually combine JSON reports from multiple processes

    master

    If you need to generate and combine reports from different processes manually:

    1. Generate individual reports: Use --pid_suffix to ensure each JSON file ends with the process ID. You can also specify a custom output directory with --output_dir or a specific filename with -o.
    2. Combine reports: Use the viztracer --combine command pointing to the generated JSON files. You can use --output_file to name the final combined report.

    Recommended workflow:

    # 1. Generate reports with PID suffixes in a temp directory
viztracer --pid_suffix --output_dir ./temp_dir single_process.py

# 2. Combine all JSON files in that directory
viztracer --combine ./temp_dir/*.json
    viztracer --pid_suffix single_process.py
# or
viztracer -o process1.json single_process.py

# With output directory
viztracer --pid_suffix --output_dir ./temp_dir single_process.py

# Combining
viztracer --combine ./temp_dir/*.json

  2. Use third-party plugins via CLI

    master

    To use a third-party plugin with VizTracer via the command line, install the plugin package using pip and then pass the plugin module name to the --plugins flag.

    If a package contains multiple plugins, specify the full module path. You can also pass arguments to the plugin by wrapping the module name and arguments in double quotes.

  3. Use Sparse Logging with @log_sparse

    master

    Sparse logging allows you to record only specific functions, which is useful for getting a high-level overview of large projects without the noise of every function call.

    Workflow:

    1. Decorate the target functions with @log_sparse.
    2. Run the script using the --log_sparse CLI flag.

    Decorator Options:

    • @log_sparse: Logs only the decorated function.
    • @log_sparse(stack_depth=N): Logs the decorated function and its descendants up to depth N. (Note: Nested @log_sparse calls only respect the outermost depth limit).
    • @log_sparse(dynamic_tracer_check=True): Required if you are using the tracer as a context manager or via %%viztracer in Jupyter to ensure the decorator works correctly within the created context.

    Limitations:

    • Some advanced features may not work in sparse mode.
    • @log_sparse acts as a no-op if the script is not run with the --log_sparse flag.
    • For logging specific pieces of code (rather than full functions), use Duration Event which is compatible with sparse logging.

  5. Implement generic multi-process support

    master

    To integrate VizTracer into third-party libraries that use multiple processes, follow these steps:

    1. The main process must be executed via viztracer (inline usage is not supported for this method).
    2. Retrieve the init_kwargs dictionary from the main process using get_tracer().init_kwargs.
    3. Pass this dictionary to the sub-process.
    4. In the sub-process, instantiate a VizTracer object using these arguments, register the exit, and start the tracer.
    # init_kwargs is the argument from main process
tracer = VizTracer(**init_kwargs)
tracer.register_exit()
tracer.start()

  6. Use VizTracer in Jupyter Notebooks

    master

    To use VizTracer in Jupyter, load the extension and use the %%viztracer cell magic.

    %load_ext viztracer

%%viztracer
# Your code here

    Supported arguments for the %%viztracer magic include:

    • --port
    • --output_file
    • --max_stack_depth
    • --ignore_c_function
    • --ignore_frozen
    • --log_func_args
    • --log_print
    • --log_sparse
    # You need to load the extension first
%load_ext viztracer

%%viztracer
# Your code after

# you can define arguments of VizTracer in magic
%%viztracer -p 8888
# Your code after

  7. Trace os.fork() and os.exec()

    master

    VizTracer supports os.fork(). The main process will wait for forked processes to finish.

    If you use os.exec() or its variants after a fork, VizTracer will only record activity occurring before the os.exec() call. To record activity after an os.exec(), you must use the Generic Multi Process Support method.

  10. Trace multiprocessing and concurrent.futures

    master

    VizTracer supports multiprocessing and concurrent.futures for both fork and spawn process types. It automatically makes the main process wait for all child processes to finish so the final report includes all process data. You can interrupt this waiting behavior using Ctrl+C.

    Limitation: On Windows, multiprocessing.Pool is not supported because VizTracer cannot gracefully catch the exit of those processes.

    viztracer my_script_using_multiprocess.py

  12. Use Magic Comments for Zero-Overhead Logging

    master

    Magic comments allow you to insert logging instructions that have zero overhead and no side effects when running your program normally. They are only triggered when running via viztracer with the --magic_comment flag.

    Supported Magic Comments:

    • # !viztracer: log_instant("name", args=...): Logs an instant event.
    • # !viztracer: log_var("name", var): Logs a variable.
    • # !viztracer: log: An inline magic comment. If used on an assignment (a = 3 # !viztracer: log), it logs the assigned value. If used on a function call (f() # !viztracer: log), it logs an instant event indicating the line was executed.
    • # !viztracer: log if <condition>: Performs a conditional log (e.g., a = 3 # !viztracer: log if a == 3).

    To enable this, run your program with the --magic_comment flag.

    viztracer --magic_comment your_program.py