Trace or track Python statement execution (trace)

The trace module in Python provides powerful tools for monitoring program execution, generating coverage reports, and tracking function calls. It helps developers debug code by showing which lines execute and how many times.

Example Files Setup

Let's create two Python files to demonstrate the trace module features ?

myfunctions.py

#myfunctions.py
import math

def area(x):
    a = math.pi * math.pow(x, 2)
    return a

def factorial(x):
    if x == 1:
        return 1
    else:
        return x * factorial(x - 1)

mymain.py

#mymain.py
import myfunctions

def main():
    x = 5
    print('area =', myfunctions.area(x))
    print('factorial =', myfunctions.factorial(x))

if __name__ == '__main__':
    main()

Command Line Interface

The trace module has a command line interface accessible via python -m trace. The most important options include --trace, --count, and --listfuncs.

Line-by-Line Execution Tracing

The --trace option displays program lines as they execute. Use --ignore-dir to exclude standard library directories ?

python -m trace --ignore-dir=../lib --trace mymain.py

mymain.py(2): def main():
mymain.py(7): if __name__=='__main__':
mymain.py(8):     main()
--- modulename: mymain, funcname: main
mymain.py(3):     x = 5
mymain.py(4):     print('area =', myfunctions.area(x))
--- modulename: myfunctions, funcname: area
myfunctions.py(3):     a = math.pi * math.pow(x, 2)
myfunctions.py(4):     return a
area = 78.53981633974483
mymain.py(5):     print('factorial =', myfunctions.factorial(x))
--- modulename: myfunctions, funcname: factorial
myfunctions.py(6):     if x == 1:
myfunctions.py(9):         return x * factorial(x - 1)
--- modulename: myfunctions, funcname: factorial
myfunctions.py(6):     if x == 1:
myfunctions.py(9):         return x * factorial(x - 1)
--- modulename: myfunctions, funcname: factorial
myfunctions.py(6):     if x == 1:
myfunctions.py(7):         return 1
factorial = 120

Code Coverage Analysis

The --count option generates coverage files showing how many times each line executed ?

python -m trace --count mymain.py

This creates .cover files for each module. The numbers show execution counts ?

# myfunctions.cover
    1: import math
    1: def area(x):
    1:     a = math.pi * math.pow(x, 2)
    1:     return a
    1: def factorial(x):
    5:     if x == 1:
    1:         return 1
       else:
    4:         return x * factorial(x - 1)

Coverage Summary

Combine --count with --summary for a brief coverage report ?

python -m trace --count --summary mymain.py

area = 78.53981633974483
factorial = 120
lines   cov%   module   (path)
    8   100%   myfunctions   (myfunctions.py)
    7   100%   mymain   (mymain.py)

Function Call Tracking

The --listfuncs option shows all functions called during execution ?

python -m trace --listfuncs mymain.py

Add --trackcalls to see calling relationships between functions ?

python -m trace --listfuncs --trackcalls mymain.py

Common Options

Conclusion

The trace module is invaluable for debugging and code analysis. Use --trace for step-by-step execution, --count for coverage analysis, and --listfuncs for understanding function call patterns.