pyinstrument

文档

Pyinstrument是一个Python分析器。分析器是一个帮助您优化代码（使其更快）的工具。为了获得最大的速度提升，您应该关注程序中运行最慢的部分。Pyinstrument可以帮助您找到它！

☕️ 不知从何开始？查看来自calmcode.io的视频教程！

安装

pip install pyinstrument

Pyinstrument支持Python 3.8+。

要从git checkout运行Pyinstrument，有一个构建步骤。有关更多信息，请参阅贡献。

文档

要了解如何使用pyinstrument或检查参考，请访问文档。

已知问题

• 在Docker容器内分析代码可能会产生一些奇怪的结果，因为pyinstrument使用的gettimeofday系统调用在该环境中较慢。参见#83
• 当使用pyinstrument script.py，其中script.py包含使用pickle序列化的类时，可能会遇到错误，因为序列化机制不知道__main__在哪里。参见此问题以获取解决方案

变更日志

v4.7.3

2024年9月6日

• 修复了4.7.0版本中引入的一个bug，该bug会导致在分析包含非典型局部变量的代码时，分析器崩溃，尤其是某些pytest扩展(#332)
• 修复了一个bug，该bug会导致pyinstrument在Python 3.12或更高版本中无法导入如glom之类的包，这些包会修改locals()字典(#336)
• 修复了一些平台上出现的UnicodeDecodeError错误(#330)
• 修复了一些情况下发生的除以零错误
• IPython集成采取了更大的步骤来确保干净的配置输出，通过确保在打印之前删除内部框架(#321)

v4.7.2

2024年8月5日

• 添加CPython 3.13的wheel文件
• 修复了导致HTML输出在某些浏览器上下文中无法渲染的bug(#328)

v4.7.1

2024年8月2日

• 修复了与PyPI上传相关的问题

v4.7.0

2024年8月1日

• 添加了一个新的、方便的API，用于分析Python代码的片段！现在您可以使用with块或函数/方法装饰器来分析。这将分析代码并将简短的读数打印到终端(#327)
• 添加了新的、开销较低的计时选项。Pyinstrument在每次Python函数调用时都会调用计时器，这在提供快速计时的系统上效果很好，但在每个都需要系统调用的系统上，如某些Docker环境，它会增加显著的开销。Pyinstrument现在将检测慢速计时器，并显示警告并提供两种选择。您可以启用“计时线程”，将计时工作负载从被分析的线程卸载，或者，如果您对较低的分辨率满意，可以选择使用“粗略”计时器，该计时器在某些Linux系统上提供(#273)
• 在HTML输出中Alt点击行以折叠/展开整个树(#325)
• 向控制台输出添加了flat参数，以呈现函数的平面列表(#294)
• 添加了Litestar示例配置和文档(#284)
• 初步支持Python 3.13(#322)

v4.6.2

2024年1月26日

• 修复了pstats渲染器中的bug，输出中可能会看到额外的框架(#287)
• 向Profiler.output_html添加了show_all选项

v4.6.1

2023年11月8日

• 修复了IPython魔法%pyinstrument中不想要的变量展开的bug(#278)

v4.6.0

2023年10月12日

• 添加了-c功能，允许直接从命令行分析代码，如python -c。(#271)
• 添加了一个方便的方法Profiler.write_html，用于直接将HTML输出写入文件(#266)

v4.5.3

2023年9月7日

• 修复了在打包过程中导致无法上传到PyPI的问题

v4.5.2

2023年9月1日

• 在HTML输出的标题中显示程序名称(#260)
• 提高程序名称捕获的鲁棒性，通过抵抗其他程序修改sys.argv(#258)
• 添加了对Python 3.12的支持(#246)

v4.5.1

2023年7月22日

• 修复了由于__tracebackhide__（#255）导致删除框架时输出中出现[X frames hidden]的bug。
• 修复了内置代码在控制台输出中显示None文件路径的bug（#254）。
• 一些文档改进（#251）。

v4.5.0

2023年6月5日

• 添加了控制台渲染器的平面模式，可以通过在命令行中传递-p flat来启用。此模式显示按自时间测量的最重的框架，这在某些代码库中可能很有用（#240）。
• 添加了保存pstats文件的功能。这是stdlib中cprofile使用的文件格式。它比pyinstrument配置文件详细，但与更多工具兼容（#236）。
• 修复了--show-all选项的一个细节 - 当提供此选项时，pyinstrument将不再删除Python内部框架（#239）。
• 在HTML渲染器内部，现在使用Svelte渲染前端，这意味着配置文件更少地捆绑javascript，因此文件更小（#222）。

v4.4.0

2022年11月5日

• 在控制台和HTML输出中添加了方法类的名称（#203）。
• 修复了导致pyinstrument机制出现在配置文件开头的bug（#215）。
• 设置了__traceback_hide__局部变量的框架现在将从输出中删除（#217）。
• Jupyter/IPython魔法现在支持async/await，如果您使用带有--async_mode=enabled标志运行，则支持（#212）。
• 修复了在线程中捕获多个根框架时的崩溃问题 - 这可能会在gevent中发生。
• 对后端进行了重大重构，允许捕获不仅仅是静态信息。目前这仅用于支持类名功能，但未来还有更多！

v4.3.0

2022年8月21日

• 在HTML输出中添加了按钮，可以在绝对时间和比例（百分比）时间之间切换。
• 添加了命令行标志--interval（秒，默认0.001），用于更改pyinstrument采样程序的间隔。这对于长时间运行程序很有用，其中增加间隔可以减少内存开销。
• 包括CPython 3.11的wheels。

v4.2.0

• 添加了命令行选项-p --render-option，允许任意设置渲染选项。这允许您从命令行设置选项，如filter_threshold，例如通过执行类似pyinstrument -p processor_options.filter_threshold=0的操作。

  以下是该选项的帮助输出

    -p RENDER_OPTION, --render-option=RENDER_OPTION
                      options to pass to the renderer, in the format
                      'flag_name' or 'option_name=option_value'. For
                      example, to set the option 'time', pass '-p
                      time=percent_of_total'. To pass multiple options, use
                      the -p option multiple times. You can set processor
                      options using dot-syntax, like '-p
                      processor_options.filter_threshold=0'. option_value is
                      parsed as a JSON value or a string.
  

• 添加了将控制台输出中的时间视为百分比而不是绝对时间的功能。使用ConsoleRenderer选项time='percent_of_total'，或在命令行中，使用-p，例如pyinstrument -p time=percent_of_total。

• 添加了加载和保存pyinstrument会话的命令行选项。您可以使用-r session将pyinstrument会话的原始数据保存下来，例如pyinstrument -r session -o session.pyisession myscript.py。加载是通过--load完成的，例如pyinstrument --load session.pyisession。

• 命令行输出格式由-o输出文件的扩展名推断。因此，如果您执行pyinstrument -o profile.html myscript.py，您不需要提供-r html，pyinstrument将自动使用HTML渲染器。或者如果您执行pyinstrument -o profile.pyisession myscript.py，它将保存原始会话对象。

• 将FastAPI和pytest的使用示例添加到文档中。

• 修复了使用async_mode=strict时导致NotImplementedError的bug。

• 添加了对Python 3.11的支持。

v4.1.1

• 修复了当使用speedscope渲染器时，PYINSTRUMENT_PROFILE_DIR_RENDERER输出错误文件扩展名的issue。

v4.1.0

• 现在您可以在IPython笔记本中使用pyinstrument原生！只需在笔记本顶部使用%load_ext pyinstrument，然后在您想要配置文件的单元中使用%%pyinstrument。
• 添加了对speedscope格式的支持。这提供了一种使用pyinstrument查看交互式火焰图的途径。要使用，请使用pyinstrument -r speedscope进行配置文件，然后上传到speedscope网络应用程序。
• 现在，您可以使用 PYINSTRUMENT_PROFILE_DIR_RENDERER 选项来配置 Django 中间件文件输出的渲染器。
• 增加了 Linux aarch64 (64位ARM) 的wheel版本。

v4.0.4

• 修复了安装名为 'test' 的包时与 pyinstrument 共存的问题
• 使用更现代的C API来解决Python 3.10上的弃用警告。
• 一些文档修正

v4.0.3

• 支持CPython 3.10
• 改进了从多个线程尝试使用Profiler时的错误信息
• 修复了渲染包含FrameGroup中模块的会话时的崩溃问题

v4.0.2

• 修复了一些打包问题

v4.0.0

• 异步支持！Pyinstrument现在可以检测异步任务是否遇到了await，并跟踪在此await下异步上下文外的耗时。

  例如，这里有一个包含异步任务的简单脚本，该任务执行sleep操作

  import asyncio
  from pyinstrument import Profiler
  
  async def main():
      p = Profiler(async_mode='disabled')
  
      with p:
          print('Hello ...')
          await asyncio.sleep(1)
          print('... World!')
  
      p.print()
  
  asyncio.run(main())
  

  在Pyinstrument 4.0.0之前，我们只能看到运行循环中的时间，如下所示

    _     ._   __/__   _ _  _  _ _/_   Recorded: 18:33:03  Samples:  2
   /_//_/// /_\ / //_// / //_'/ //     Duration: 1.006     CPU time: 0.001
  /   _/                      v3.4.2
  
  Program: examples/async_example_simple.py
  
  1.006 _run_once  asyncio/base_events.py:1784
  └─ 1.005 select  selectors.py:553
        [3 frames hidden]  selectors, <built-in>
           1.005 kqueue.control  <built-in>:0
  

  现在，使用pyinstrument 4.0.0，我们得到

    _     ._   __/__   _ _  _  _ _/_   Recorded: 18:30:43  Samples:  2
   /_//_/// /_\ / //_// / //_'/ //     Duration: 1.007     CPU time: 0.001
  /   _/                      v4.0.0
  
  Program: examples/async_example_simple.py
  
  1.006 main  async_example_simple.py:4
  └─ 1.005 sleep  asyncio/tasks.py:641
        [2 frames hidden]  asyncio
           1.005 [await]
  

  有关更多信息，请参阅异步分析文档和Profiler.async_mode 属性。

• Pyinstrument有一个文档网站，包括完整的Python API文档！

v3.4.2

• 修复了导致命令行上忽略 --show、--show-regex、--show-all 的bug。

v3.4.1

• 底层现代化

v3.4.0

• 为Profiler方法的 output_html() 和 open_in_browser() 添加了 timeline 选项（布尔值）。

v3.3.0

• 修复了 pyinstrument -m module 的问题，其中pyinstrument找不到当前目录中的模块。
• 停止支持Python 2.7和3.5。旧版本将保留在PyPI上，pip应自动选择正确的版本。

v3.2.0

• 增加了跟踪C函数耗时的能力。注意 - 由于Python记录帧的限制，Pyinstrument将记录C函数的耗时为“叶”函数。例如，“Python -> C -> Python”被记录为“Python -> Python”，但“Python -> Python -> C”将被正确归因。（#103）

v3.1.2

• 修复了报告中出现 <__array_function__ internals> 帧的问题，这些帧被错误地显示为应用程序代码。

v3.1.1

• 添加了对HTML和JSON渲染器的timeline模式的支持。
• 同时以tarball和通用wheel的形式发布。

v3.1.0

• 在Django中间件中添加了PYINSTRUMENT_SHOW_CALLBACK选项，用于添加条件以显示配置文件（可以在实时服务器上运行pyinstrument！）
• 修复了Django中间件中的bug，由于Unicode错误，文件不会写入。

v3.0.3

• 修复了在Windows上Django中间件的bug，由于我们在配置文件路径中尝试放置非法字符'?'，导致分析失败。（#66）

v3.0.2

• 添加了 --show 和 --show-regex 选项，用于标记要显示的某些文件。这有助于在特定模块中进行分析，同时隐藏其他模块。例如，pyinstrument --show '*/sympy/*' script.py。

v3.0.1

• 修复了#60：将所有参数传递给-m module_name后面的调用模块
• 修复了在HTML/JSON输出时没有捕获帧时的崩溃问题。

v3.0.0

• Pyinstrument现在将隐藏您使用的库中的跟踪。因此，而不是显示大量的帧通过外部内容的内部，例如urllib，它允许您专注于您的代码。

  之前	之后

  要返回旧的行为，请在命令行上使用 --show-all。

• 隐藏组的“入口”帧显示，以便您知道哪个调用是问题所在

• 组中的帧也显示得很慢，例如套接字的“读取”调用

• 应用程序代码在控制台中被突出显示

• 其他指标显示在跟踪的顶部 - 时间戳、样本数、持续时间、CPU时间

• 隐藏代码由 --hide 或 --hide-regex 选项控制 - 匹配代码文件路径。

    --hide=EXPR           glob-style pattern matching the file paths whose
                          frames to hide. Defaults to '*/lib/*'.
    --hide-regex=REGEX    regex matching the file paths whose frames to hide.
                          Useful if --hide doesn't give enough control.
  

• 从命令行支持输出时间线。

    -t, --timeline        render as a timeline - preserve ordering and don't
                          condense repeated calls
  

• 由于现在有几个渲染选项，您可以使用 --load-prev 加载之前的分析会话 - pyinstrument 保留最后 10 个会话。

• 隐藏的组也可以调用应用程序代码，如下所示

  

• (内部) 记录时间线时，帧树现在是完全线性的，允许创建超级精确的帧图。

• (内部) HTML 渲染器已被重写为一个 Vue.js 应用程序。所有控制台改进都适用于 HTML 输出，而且它是交互式的。

• (内部) 添加了大量单元和集成测试！

哎呀！有关详细信息，请参阅 #49。希望您喜欢。

v2.3.0

• 大重构！
  • Recorders 已被移除。帧记录现在是 Profiler 对象内部的。这意味着 'frame' 对象更通用，这为...铺平了道路。
  • 处理器！这些是会修改树以塑造输出的函数。它们由渲染器用于将输出过滤到正确的形式。现在，而不是时间聚合记录器，分析器只使用时间线式记录（这本身就是低开销的），聚合是在处理步骤中完成的。
  • 结果是，现在可以很容易地修改树以过滤内容，并执行更高级的操作，如合并我们不关心的帧。v3.0 将会有更多使用此功能的特性！
• 移除了 Importlib 帧记录 - 您根本看不到它们。它们的子项被保留，因此导入是透明的。
• Django 配置文件名现在限制为一百个字符 (#50)
• 修复了 --html 选项的故障 (#53)
• 添加了 --version 命令行选项

v2.2.1

• 修复了在命令行中使用时崩溃的问题。

v2.2.0

• 添加了对 JSON 输出的支持。使用 pyinstrument --renderer=json scriptfile.py。 PR

• @iddan 使用 JSON 输出创建了一个 交互式查看器！

  

• 当运行 pyinstrument --html 并没有将输出重定向到文件时，pyinstrument 将将控制台输出写入临时文件，并在浏览器中打开该文件。

v2.1.0

• 添加了对通过命令行使用 pyinstrument 运行模块的支持。新语法是 -m 标志，例如 pyinstrument -m module_name！ PR

v2.0.4

• 修复了由于多线程使用 pyinstrument 而导致的崩溃。修复在 C 扩展中，请参阅 https://github.com/joerick/pyinstrument_cext/pull/3

v2.0.3

• Pyinstrument 现在可以在 with 块中使用。

  例如

  profiler = pyinstrument.Profiler()
  with profiler:
      # do some work here...
  print(profiler.output_text())
  

• 为旧版本的 Django 修复中间件

v2.0.2

• 修复了在分析具有大量堆栈帧的程序时发生的最大递归错误。

v2.0.1

• 确保在 sdist 中包含许可证。

v2.0.0

• Pyinstrument 使用了一种新的分析模式。与使用信号不同，pyintrument 使用基于 PyEval_SetProfile 的新统计分析器。这意味着没有主线程限制，没有使用 Pyinstrument 时的 IO 错误，也不需要单独的 'setprofile' 模式！

• 渲染器。用户可以通过在 Profiler.output() 上的 renderer 参数或使用命令行上的 --renderer 参数自定义 Pyinstrument 以使用替代渲染器。

• 记录器。为了支持Pyinstrument的其它用例（例如火焰图），pyinstrument现在拥有“时间线”记录器模式。此模式以线性方式记录捕获的帧，因此可以按时间线查看程序执行。

v0.13

• pyinstrument 命令。您现在可以通过在shell中运行 $ pyinstrument script.py 来从shell中分析Python脚本。这现在等同于 python -m pyinstrument。感谢 @asmeurer！

v0.12

• 在HTML跟踪中突出显示应用程序代码，以便更容易找到。

• 向Django界面添加了 PYINSTRUMENT_PROFILE_DIR 选项，该选项将所有请求的配置文件记录到指定的文件夹中的文件。这对于分析API调用非常有用。

• 向Django界面添加了 PYINSTRUMENT_USE_SIGNAL 选项，当信号模式存在问题时应使用。

贡献

设置开发环境

virtualenv --python=python3 env
. env/bin/activate
pip install --upgrade pip
pip install -r requirements-dev.txt
pre-commit install --install-hooks

获取一些示例输出

pyinstrument examples/wikipedia_article_word_count.py

运行测试

pytest

在本地运行linting检查

pre-commit run --all-files

一些预提交检查，如 isort 或 black，将自动修复它们发现的问题。因此，如果上面的命令返回错误，请再次运行它，它可能在第二次尝试时成功 :)

运行所有检查可能很慢，因此您也可以单独运行检查，例如，格式化失败的源代码 isort 或 black 检查。

pre-commit run --all-files isort
pre-commit run --all-files black

诊断为什么 pyright 检查失败

pre-commit run --all-files pyright

HTML渲染器Vue.js应用

HTML渲染器通过在HTML文件中嵌入带有JavaScript 'bundle'的样本的JSON表示来工作，该HTML文件可以在任何Web浏览器中查看。

要编辑HTML渲染器样式，请执行

cd html_renderer
npm ci
npm run serve

在没有顶级 window.profileSession 对象的情况下启动时，它将获取一个样本配置文件，以便您可以与之一起工作。

要编译JS应用程序并将其捆绑回pyinstrument Python工具

bin/build_js_bundle.py [--force]