27.7. trace — Trace or track Python statement execution
The trace module allows you to trace program execution, generate
annotated statement coverage listings, print caller/callee relationships and
list functions executed during a program run. It can be used in another program
or from the command line.
27.7.1. Command Line Usage
The trace module can be invoked from the command line. It can be as
python -m trace --count somefile.py ...
The above will generate annotated listings of all Python modules imported during
the execution of somefile.py.
The following command-line arguments are supported:
- --trace, -t
- Display lines as they are executed.
- --count, -c
- Produce a set of annotated listing files upon program completion that shows how
many times each statement was executed.
- --report, -r
- Produce an annotated list from an earlier program run that used the
--count and --file arguments.
- --no-report, -R
- Do not generate annotated listings. This is useful if you intend to make
several runs with --count then produce a single set of annotated
listings at the end.
- --listfuncs, -l
- List the functions executed by running the program.
- --trackcalls, -T
- Generate calling relationships exposed by running the program.
- --file, -f
- Name a file containing (or to contain) counts.
- --coverdir, -C
- Name a directory in which to save annotated listing files.
- --missing, -m
- When generating annotated listings, mark lines which were not executed with
- --summary, -s
- When using --count or --report, write a brief summary to
stdout for each file processed.
- Accepts comma separated list of module names. Ignore each of the named
module and its submodules (if it is a package). May be given
- Ignore all modules and packages in the named directory and subdirectories
(multiple directories can be joined by os.pathsep). May be given multiple
27.7.2. Programming Interface
class trace.Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]])
- Create an object to trace execution of a single statement or expression. All
parameters are optional. count enables counting of line numbers. trace
enables line execution tracing. countfuncs enables listing of the functions
called during the run. countcallers enables call relationship tracking.
ignoremods is a list of modules or packages to ignore. ignoredirs is a list
of directories whose modules or packages should be ignored. infile is the
file from which to read stored count information. outfile is a file in which
to write updated count information. timing enables a timestamp relative
to when tracing was started to be displayed.
- Run cmd under control of the Trace object with the current tracing parameters.
Trace.runctx(cmd[, globals=None[, locals=None]])
- Run cmd under control of the Trace object with the current tracing parameters
in the defined global and local environments. If not defined, globals and
locals default to empty dictionaries.
Trace.runfunc(func, *args, **kwds)
- Call func with the given arguments under control of the Trace object
with the current tracing parameters.
This is a simple example showing the use of this module:
# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
# run the new command using the given tracer
# make a report, placing output in /tmp
r = tracer.results()