Filter

Sometimes, you may have too many data entries and you want to filter some of them out to either improve the performance or make the report clearer. VizTracer provides multiple filters for your needs.

Min Duration

You can ask VizTracer to only record entries that last longer than a period of time

viztracer --min_duration 0.2ms my_script.py

OR

tracer = VizTracer(min_duration=200)

Notice that with command line interface, viztracer expects a string representing a period of time, which should be in format of <val><unit>. ex. 0.2ms, 300ns, 5.5us. You can also omit the unit and it would be parsed as us, ex. 0.5 is the same as 0.5us.

But as an argument to VizTracer, it should be a number of us.

The default value of min_duration is 0, meaning every function entry is recorded.

Max Stack depth

You can limit maximum stack depth to trace by

viztracer --max_stack_depth 10 my_script.py

OR

tracer = VizTracer(max_stack_depth=10)

Include Files

You can include only certain files/folders to trace by

# -- is used to resolve ambiguity
viztracer --include_files ./src -- my_script.py

OR

tracer = VizTracer(include_files=["./src"])

Exclude Files

Similarly, you can exclude certain files/folders to trace by

# -- is used to resolve ambiguity
viztracer --exclude_files ./not_interested.py -- my_script.py

OR

tracer = VizTracer(exclude_files=["./not_interested.py"])

Ignore C Function

By default, VizTracer will trace both python and C functions. You can turn off tracing C functions by

viztracer --ignore_c_function my_script.py

OR

tracer = VizTracer(ignore_c_function=True)

Since most of the builtin functions(like append or len) are C functions which are frequently called, ignoring C functions often improves the overhead and file size significantly.

Ignore Non File

You can ask VizTracer not to trace any functions that are not in a valid file(mostly import stuff) using ignore_frozen

viztracer --ignore_frozen my_script.py

OR

tracer = VizTracer(ignore_frozen=True)

Ignore Function

It’s possible that you want to ignore some arbitrary functions and their descendants. You can do it using @ignore_function decorator

from viztracer import ignore_function
# This only works when there's a globally registered tracer
@ignore_function
def some_function():
    # nothing inside will be traced

Log Sparse

You can make VizTracer log only certain functions using --log_sparse. This is helpful when you are only interested in the time spent on specific functions for a big picture on larger projects.

First, you need to add decorator @log_sparse on the function you want to log

from viztracer import log_sparse

# @log_sparse will only log this function
@log_sparse
def function_you_want_to_log():
    # function body

# @log_sparse(stack_depth=5) will log this function and its descendants
# with a limit stack depth of 5
# Nested @log_sparse with stack_depth won't work
# (only the outermost function and its stack will be logged)
@log_sparse(stack_depth=5)
def function_you_want_to_log():
    # function body

# Use dynamic_tracer_check=True if you use tracer as a context manager (or with %%viztracer).
@log_sparse(dynamic_tracer_check=True)
def function_you_want_to_log():
    # function body

with VizTracer(log_sparse=True):
    function_you_want_to_log()

Then just call viztracer with --log_sparse

viztracer --log_sparse your_script.py

When you are using --log_sparse, due to the nature of the recording, some advanced features may not work with it.

You can leave @log_sparse as it is when you are not running the script with VizTracer. It will be like a no-op

If you want to log a piece of code, rather than a full function, please check Duration Event. Duration Event is compatible with log_sparse

To use @log_sparse in conjunction with a context manager, you must define decorating functions within the created context, or set the dynamic_tracer_check=True` argument of decorator. The second option leads to runtime checks, so it increases the overhead.