Содержание страницы

`pstats` – Статистика для профилировщиков¶pstats – Statistics for profilers

Исходный код: Lib/pstats.py

Модуль pstats предоставляет инструменты для чтения, обработки и отображения статистики профилирования, созданной профилировщиками Python. Он читает выходные данные как от profiling.tracing (детерминированного профилировщика), так и от profiling.sampling (статистического профилировщика).

Чтение и отображение данных профиля¶Reading and displaying profile data

Класс Stats является основным интерфейсом для работы с данными профиля. Он может читать статистику из файлов или напрямую из объекта Profile.

Загрузка статистики из файла и вывод базового отчета:

import pstats

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

Объект Stats предоставляет методы для сортировки и фильтрации данных перед выводом. Например, чтобы увидеть десять функций с наибольшим кумулятивным временем:

from pstats import SortKey

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

Работа со статистикой¶Working with statistics

Класс 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()

Фильтрация вывода¶Filtering output

Метод 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)

Анализ отношений вызовов¶Analyzing call relationships

Метод print_callers() показывает, какие функции вызывали каждую отображаемую функцию:

p.print_callers()

Метод print_callees() показывает обратное отношение, перечисляя, какие функции вызывала каждая отображаемая функция:

p.print_callees()

Оба метода принимают те же аргументы ограничения, что и print_stats().

Объединение нескольких профилей¶Combining multiple profiles

Статистику из нескольких сеансов профилирования можно объединить в один объект Stats:

# Загрузить несколько файлов за один раз
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')

# Или добавлять файлы постепенно
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')

При объединении файлов статистика для одинаковых функций (одинаковый файл, строка и имя) накапливается, давая обобщённое представление по всем сеансам профилирования.

Класс `Stats`¶The Stats class

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

Создание объекта статистики из данных профиля.

Аргументами могут быть имена файлов (строки или объекты, подобные пути) или объекты Profile. Если указано несколько источников, их статистика объединяется.

Аргумент поток данных указывает, куда записывается вывод print_stats() и связанных методов. По умолчанию он равен sys.stdout.

Формат данных профиля зависит от версии Python, в которой он был создан. Нет гарантии совместимости между версиями Python или между разными профилировщиками.

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'.

Добавлено в версии 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, содержащими информацию о времени и количестве вызовов.

Добавлено в версии 3.9.

class pstats.SortKey¶

Перечисление допустимых ключей сортировки для Stats.sort_stats().

CALLS¶: Сортировать по количеству вызовов.

CUMULATIVE¶: Сортировать по накопленному времени.

FILENAME¶: Сортировать по имени файла.

LINE¶: Сортировать по номеру строки.

NAME¶: Сортировать по имени функции.

NFL¶: Сортировать по имени, затем по файлу, затем по номеру строки (числовая сортировка строк).

PCALLS¶: Сортировать по количеству примитивных (нерекурсивных) вызовов.

STDNAME¶: Сортировать по стандартному имени (строковая сортировка строк).

TIME¶: Сортировать по внутреннему времени (время внутри функции без учёта вызовов).

Интерфейс командной строки¶Command-line interface

Модуль pstats можно запустить как скрипт для интерактивного просмотра данных профилирования:

python -m pstats profile_output.prof

Откроется интерфейс, ориентированный на строки (построенный на cmd), для просмотра статистики. Введите help в приглашении, чтобы увидеть доступные команды.

См. также

profiling: Обзор инструментов профилирования Python.
profiling.tracing: Детерминированный трассирующий профилировщик.
profiling.sampling: Статистический профилировщик на основе выборки.