trace — Python 문장 실행 추적

trace 모듈을 사용하면 프로그램 실행을 추적하고, 주석이 달린 문장 커버리지 목록을 생성하고, 호출자/피호출자 관계를 출력하고, 프로그램 실행 중 실행된 함수들을 나열할 수 있어요. 다른 프로그램 안에서나 명령줄에서 사용할 수 있어요.

출처: Python documentation

본문

또한 HTML 출력과 분기 커버리지(branch coverage) 같은 고급 기능을 제공하는 인기 있는 서드파티 커버리지 도구인 Coverage.py도 참고하세요.

명령줄 사용법 (Command-Line Usage)

trace 모듈은 명령줄에서 호출할 수 있어요:

python -m trace --count -C . somefile.py ...

위 명령은 somefile.py를 실행하고, 실행 중 import된 모든 Python 모듈의 주석이 달린 목록을 현재 디렉터리에 생성해요.

--help — 사용법을 표시하고 종료
--version — 모듈의 버전을 표시하고 종료

주요 옵션 (Main options)

trace를 호출할 때 다음 옵션 중 적어도 하나를 지정해야 해요. --listfuncs 옵션은 --trace와 --count 옵션과 상호 배타적이에요.

-c, --count — 프로그램 완료 시 각 문장이 실행된 횟수를 보여주는 주석이 달린 목록 파일 세트를 생성
-t, --trace — 실행되는 대로 줄을 표시
-l, --listfuncs — 프로그램 실행으로 실행된 함수를 표시
-r, --report — --count와 --file 옵션을 사용한 이전 프로그램 실행에서 주석이 달린 목록을 생성(코드는 실행하지 않음)
-T, --trackcalls — 프로그램 실행으로 드러난 호출 관계를 표시

수정자 (Modifiers)

-f, --file=<file> — 여러 추적 실행에 걸쳐 카운트를 누적할 파일 이름. --count 옵션과 함께 사용해야 해요.
-C, --coverdir=<dir> — 보고서 파일이 들어가는 디렉터리. package.module의 커버리지 보고서는 dir/package/module.cover에 작성돼요.
-m, --missing — 주석이 달린 목록을 생성할 때 실행되지 않은 줄을 >>>>>>로 표시
-s, --summary — --count 또는 --report 사용 시 처리된 각 파일에 대한 간단한 요약을 stdout에 작성
-R, --no-report — 주석이 달린 목록을 생성하지 않음. --count로 여러 번 실행한 다음 마지막에 단일 주석 목록 세트를 생성하려는 경우 유용해요.
-g, --timing — 각 줄 앞에 프로그램 시작 이후의 시간을 붙임. 추적하는 동안에만 사용해요.

필터 (Filters)

이 옵션들은 여러 번 반복할 수 있어요.

--ignore-module=<mod> — 주어진 각 모듈 이름과 그 하위 모듈(패키지인 경우)을 무시. 인자는 쉼표로 구분된 이름 목록일 수 있어요.
--ignore-dir=<dir> — 지정된 디렉터리와 하위 디렉터리의 모든 모듈과 패키지를 무시. 인자는 os.pathsep으로 구분된 디렉터리 목록일 수 있어요.

프로그래매틱 인터페이스 (Programmatic Interface)

classtrace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

단일 문장이나 표현식의 실행을 추적하는 객체를 만들어요. 모든 매개변수는 선택적이에요. count는 줄 번호 카운팅을 활성화하고, trace는 줄 실행 추적을 활성화하고, countfuncs는 실행 중 호출된 함수 목록 표시를 활성화하고, countcallers는 호출 관계 추적을 활성화해요. ignoremods는 무시할 모듈이나 패키지 목록, ignoredirs는 모듈이나 패키지를 무시할 디렉터리 목록이에요. infile은 저장된 카운트 정보를 읽을 파일 이름, outfile은 업데이트된 카운트 정보를 쓸 파일 이름이에요. timing은 추적이 시작된 시점을 기준으로 하는 타임스탬프 표시를 활성화해요.

run(cmd)

현재 추적 매개변수로 명령을 실행하고 그 실행에서 통계를 수집해요. cmd는 exec()에 전달하기 적합한 문자열이나 코드 객체여야 해요.

runctx(cmd, globals=None, locals=None)

현재 추적 매개변수로, 정의된 전역 및 지역 환경에서 명령을 실행하고 통계를 수집해요. 정의되지 않으면 globals와 locals는 빈 사전으로 기본 설정돼요.

runfunc(func, /, *args, **kwds)

현재 추적 매개변수로 Trace 객체의 제어 하에 주어진 인자로 func를 호출해요.

results()

주어진 Trace 인스턴스에 대한 run, runctx, runfunc의 모든 이전 호출의 누적 결과를 담은 CoverageResults 객체를 반환해요. 누적된 추적 결과를 재설정하지 않아요.

classtrace.CoverageResults

Trace.results()로 생성되는 커버리지 결과 컨테이너예요. 사용자가 직접 생성해서는 안 돼요.

update(other) — 다른 CoverageResults 객체의 데이터를 병합
write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False) — 커버리지 결과를 작성. show_missing은 적중(hit)이 없는 줄을 표시하고, summary는 모듈별 커버리지 요약을 출력에 포함시켜요. coverdir는 커버리지 결과 파일이 출력될 디렉터리를 지정하며, None이면 각 소스 파일의 결과가 해당 디렉터리에 배치돼요. ignore_missing_files가 True이면 더 이상 존재하지 않는 파일의 커버리지 카운트는 조용히 무시돼요. 그렇지 않으면 누락된 파일은 FileNotFoundError를 일으켜요.

프로그래매틱 인터페이스 사용 간단 예제:

import sys
import trace

# Trace 객체를 만들어 무엇을 무시할지, 추적 또는 줄 카운팅을 할지 지정
tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix], trace=0, count=1)

# 주어진 tracer로 새 명령 실행
tracer.run('main()')

# 보고서 생성, 현재 디렉터리에 출력 배치
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")

더 알아보기 (Learn more)

Python 공식 문서