`pstats` — 프로파일러 통계¶

소스 코드: Lib/pstats.py

pstats 모듈은 파이썬 프로파일러에 의해 생성된 프로파일링 통계를 읽고, 조작하고, 표시하는 도구를 제공합니다. 이 모듈은 profiling.tracing (결정론적 프로파일러)과 profiling.sampling (통계적 프로파일러) 모두에서 출력된 데이터를 읽어옵니다.

프로파일 데이터 읽기 및 표시¶

Stats 클래스는 프로파일 데이터를 처리하는 주요 인터페이스입니다. 파일이나 Profile 객체에서 직접 통계를 읽어올 수 있습니다.

파일에서 통계를 불러와 기본 보고서를 인쇄합니다:

import pstats

p = pstats.Stats('profile_output.prof')
p.print_stats()

Stats 객체는 출력 전에 데이터를 정렬하고 필터링하는 메서드들을 제공합니다. 예를 들어, 누적 시간이 가장 높은 10개 함수를 확인하려면 다음과 같이 합니다:

from pstats import SortKey

p = pstats.Stats('profile_output.prof')
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

통계 데이터 처리¶

Stats 클래스는 메서드 체이닝을 지원하여 여러 작업을 편리하게 수행할 수 있습니다:

p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()

strip_dirs() 메서드는 파일 이름에서 디렉터리 경로를 제거하여 출력을 더 간결하게 만듭니다. sort_stats() 메서드는 정렬 순서를 제어하기 위해 다양한 키를 허용합니다.

서로 다른 정렬 키는 성능의 서로 다른 측면을 강조합니다:

from pstats import SortKey

# 가장 많은 누적 시간을 소비하는 함수
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

# 자신의 코드에서 가장 많은 시간을 소비하는 함수
p.sort_stats(SortKey.TIME).print_stats(10)

# 이름순으로 정렬된 함수
p.sort_stats(SortKey.NAME).print_stats()

출력 필터링¶

print_stats() 메서드는 표시될 함수를 필터링하는 제한 사항을 인자로 받습니다. 제한 사항은 정수(개수 제한), 0과 1 사이의 실수(백분율 선택), 또는 문자열(정규 표현식을 통한 함수 이름 매칭)이 될 수 있습니다.

상위 10%만 인쇄:

p.print_stats(.1)

“init”을 포함하는 이름의 함수만 인쇄:

p.print_stats('init')

제한 사항 결합(순차적으로 적용됨):

# 상위 10% 중 "init"을 포함하는 것만 선택
p.print_stats(.1, 'init')

# "foo:"와 일치하는 파일 내의 함수 중 상위 50%로 제한
p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)

호출 관계 분석¶

print_callers() 메서드는 표시된 각 함수를 호출한 함수가 무엇인지 보여줍니다:

p.print_callers()

print_callees() 메서드는 반대 관계를 보여주며, 각 표시된 함수가 어떤 함수를 호출했는지 나열합니다:

p.print_callees()

두 메서드 모두 print_stats() 와 동일한 제한 인자를 수용합니다.

여러 프로파일 결합¶

여러 번의 프로파일링 실행 결과로 얻은 통계를 하나의 Stats 객체로 합칠 수 있습니다:

# 여러 파일을 한 번에 로드
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')

# 또는 파일들을 점진적으로 추가
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')

파일을 결합할 때 동일한 함수(동일한 파일, 줄, 이름)에 대한 통계가 누적되어 모든 프로파일링 실행에 대한 통합된 뷰를 제공합니다.

`Stats` 클래스¶

class pstats.Stats(*filenames_or_profile, stream=sys.stdout)¶

프로파일 데이터로부터 통계 객체를 생성합니다.

인자는 파일 이름(문자열 또는 경로 유사 객체) 또는 Profile 객체일 수 있습니다. 여러 소스가 제공되면 해당 통계들이 결합됩니다.

stream 인자는 print_stats() 및 관련 메서드의 출력이 기록될 위치를 지정합니다. 기본값은 sys.stdout 입니다.

프로파일 데이터 형식은 이를 생성한 파이썬 버전에 종속적입니다. 파이썬 버전 간 또는 서로 다른 프로파일러 간에 호환성이 보장되지 않습니다.

strip_dirs()¶

모든 파일 이름에서 선행 경로 정보를 제거합니다.

이 메서드는 객체를 직접 수정하고 메서드 체이닝을 위해 이를 반환합니다. 경로를 제거한 후의 통계는 무작위 순서로 간주됩니다.

경로를 제거하여 두 함수가 구별할 수 없게 되는 경우(동일한 파일 이름, 줄 번호, 함수 이름), 해당 통계는 하나의 항목으로 결합됩니다.

add(*filenames)¶

추가 파일의 프로파일링 데이터를 추가합니다.

파일은 동일한 프로파일러 유형에 의해 생성되어야 합니다. 동일한 함수의 통계는 누적됩니다.

dump_stats(filename)¶

현재 통계를 파일에 저장합니다.

파일이 존재하지 않으면 생성하고, 이미 존재하면 덮어씁니다. 저장된 데이터는 새로운 Stats 객체를 생성하여 로드할 수 있습니다.

sort_stats(*keys)¶

지정된 기준에 따라 통계를 정렬합니다.

각 키는 문자열 또는 SortKey 열거형 멤버가 될 수 있습니다. 여러 개의 키를 제공할 경우, 뒤에 오는 키는 앞선 키에서 발생한 동점 상황을 해결합니다.

더 나은 오류 검사를 제공하므로 문자열보다 SortKey 열거형 멤버를 사용하는 것이 권장됩니다:

from pstats import SortKey
p.sort_stats(SortKey.CUMULATIVE)

유효한 정렬 키:

문자열	열거형	의미
`'calls'`	`SortKey.CALLS`	호출 수
`'cumulative'`	`SortKey.CUMULATIVE`	누적 시간
`'cumtime'`	해당 없음	누적 시간
`'file'`	해당 없음	파일명
`'filename'`	`SortKey.FILENAME`	파일명
`'module'`	해당 없음	파일명
`'ncalls'`	해당 없음	호출 수
`'pcalls'`	`SortKey.PCALLS`	프리미티브 호출 수
`'line'`	`SortKey.LINE`	줄 번호
`'name'`	`SortKey.NAME`	함수 이름
`'nfl'`	`SortKey.NFL`	이름/파일/줄
`'stdname'`	`SortKey.STDNAME`	표준 이름
`'time'`	`SortKey.TIME`	내부 시간
`'tottime'`	해당 없음	내부 시간

통계에 대한 모든 정렬은 내림차순(가장 많은 시간이 소요된 항목이 먼저)이며, 이름, 파일 및 줄 번호 정렬은 오름차순(알파벳 순서)입니다.

SortKey.NFL 과 SortKey.STDNAME 의 차이점은 NFL이 줄 번호를 숫자로 정렬하는 반면 STDNAME은 문자열로 정렬한다는 것입니다. sort_stats(SortKey.NFL) 은 sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE) 과 동일합니다.

하위 호환성을 위해 숫자 인자 -1, 0, 1, 2 도 허용되며, 각각 'stdname', 'calls', 'time', 'cumulative' 를 의미합니다.

Added in version 3.7: SortKey 열거형.

reverse_order()¶

현재 정렬 순서를 반전합니다.

기본적으로 정렬 방향은 정렬 키에 적합하게 선택됩니다(시간 기반 키는 내림차순, 이름 기반 키는 오름차순). 이 메서드는 그 선택을 반전시킵니다.

print_stats(*restrictions)¶

프로파일링 통계 보고서를 인쇄합니다.

출력에는 데이터를 요약하는 헤더 줄이 포함되며, 그 뒤에 마지막 sort_stats() 호출에 따라 정렬된 함수 통계 표가 이어집니다.

제약 사항은 출력을 필터링합니다. 각 제약 사항은 다음 중 하나입니다:

정수: 출력 항목 수를 해당 수로 제한합니다.
0.0에서 1.0 사이의 부동 소수점: 해당 비율만큼의 항목을 선택합니다.
문자열: 정규 표현식을 통해 함수 이름을 매치합니다.

제약 사항은 순차적으로 적용됩니다. 예를 들어:

print_stats(.1, 'foo:')

먼저 상위 10%로 제한한 다음, ‘foo:’와 일치하는 함수만 필터링합니다.

print_callers(*restrictions)¶

통계에 포함된 각 함수의 호출자를 인쇄합니다.

필터링된 결과의 각 함수에 대해 어떤 함수가 이를 호출했는지와 횟수를 표시합니다.

profiling.tracing (또는 cProfile)을 사용하는 경우, 각 호출자 줄에는 세 개의 숫자가 표시됩니다. 해당 호출자의 호출 횟수와 해당 특정 호출에 소요된 총 시간 및 누적 시간입니다.

print_stats() 와 동일한 제약 인자를 허용합니다.

print_callees(*restrictions)¶

통계 내의 각 함수가 호출한 함수들을 인쇄합니다.

이는 print_callers() 의 반대 작업으로, 나열된 각 함수가 어떤 함수를 호출했는지 보여줍니다.

print_stats() 와 동일한 제약 인자를 허용합니다.

get_stats_profile()¶

통계를 포함하는 StatsProfile 객체를 반환합니다.

반환된 객체는 프로파일 데이터를 프로그램 방식으로 접근할 수 있게 하며, 함수 이름은 실행 시간 및 호출 횟수 정보가 포함된 FunctionProfile 객체에 매핑됩니다.

Added in version 3.9.

class pstats.SortKey¶

Stats.sort_stats() 를 위한 유효한 정렬 키의 열거형입니다.

CALLS¶: 호출 수에 따라 정렬합니다.

CUMULATIVE¶: 누적 시간에 따라 정렬합니다.

FILENAME¶: 파일명에 따라 정렬합니다.

LINE¶: 줄 번호에 따라 정렬합니다.

NAME¶: 함수 이름에 따라 정렬합니다.

NFL¶: 이름, 파일, 줄 번호(숫자 기반 줄 정렬) 순으로 정렬합니다.

PCALLS¶: 프리미티브(비재귀적) 호출 수에 따라 정렬합니다.

STDNAME¶: 표준 이름(문자열 기반 줄 정렬)에 따라 정렬합니다.

TIME¶: 내부 시간(하위 호출을 제외한 함수 내 소요 시간)에 따라 정렬합니다.

명령 줄 인터페이스¶

pstats 모듈을 스크립트로 호출하여 프로파일 데이터를 대화식으로 탐색할 수 있습니다:

python -m pstats profile_output.prof

이것은 통계를 검토하기 위한 줄 지향 인터페이스(cmd 기반)를 엽니다. 프롬프트에서 help 를 입력하여 사용 가능한 명령을 확인하십시오.

profiling: 파이썬 프로파일링 도구 개요.
profiling.tracing: 결정론적 추적 프로파일러.
profiling.sampling: 통계적 샘플링 프로파일러.