pyinstrument

文档

Pyinstrument 是一个 Python 性能分析器。性能分析器是一种帮助你优化代码、提高运行速度的工具。要获得最大的速度提升，你应该专注于程序中最慢的部分。Pyinstrument 可以帮助你找到它！

☕️ 不知道从哪里开始？看看这个来自 calmcode.io 的视频教程吧！

安装

pip install pyinstrument

Pyinstrument 支持 Python 3.8+。

要从 git 检出运行 Pyinstrument，需要进行构建步骤。 查看贡献部分了解更多信息。

文档

要了解如何使用 pyinstrument，或查看参考，请前往文档。

已知问题

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

更新日志

v4.7.2

2024年8月5日

• 添加 CPython 3.13 轮子
• 修复了在某些浏览器环境中导致 HTML 输出无法渲染的错误 (#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 渲染器的一个错误，该错误导致输出中可能出现额外的帧。(#287)
• 为 Profiler.output_html 添加了 show_all 选项

v4.6.1

2023年11月8日

• 修复了 IPython 魔术命令 %pyinstrument 中不需要的变量展开问题 (#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__ 导致帧被删除时输出中出现 [X frames hidden] 的错误 (#255)
• 修复了导致内置代码在控制台输出中显示文件路径为 None 的错误 (#254)
• 一些文档改进 (#251)

v4.5.0

2023年6月5日

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

v4.4.0

2022年11月5日

• 在控制台和 HTML 输出中添加了方法的类名 (#203)
• 修复了导致 pyinstrument 机制出现在配置文件开头的错误 (#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 的轮子。

v4.2.0

• 添加了命令行选项 -p --render-option，允许任意设置渲染选项。这让你可以从命令行设置诸如 filter_threshold 的选项，方法是执行类似 pyinstrument -p processor_options.filter_threshold=0 的命令。 以下是选项的帮助输出:

  -p RENDER_OPTION, --render-option=RENDER_OPTION
                        传递给渲染器的选项,格式为'标志名'或'选项名=选项值'。
                        例如,要设置'time'选项,传递'-p time=percent_of_total'。
                        要传递多个选项,多次使用-p选项。你可以使用点语法
                        设置处理器选项,如'-p processor_options.filter_threshold=0'。
                        选项值解析为JSON值或字符串。

• 添加了在控制台输出中将时间显示为百分比而不是绝对时间的功能。使用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的错误。
• 添加了对Python 3.11的支持

v4.1.1

• 修复了导致PYINSTRUMENT_PROFILE_DIR_RENDERER与speedscope渲染器一起使用时输出错误文件扩展名的问题。

v4.1.0

• 现在您可以在IPython笔记本中原生使用pyinstrument!只需在笔记本顶部使用%load_ext pyinstrument,然后在要分析的单元格中使用%%pyinstrument。
• 添加了对speedscope格式的支持。这提供了一种使用pyinstrument查看交互式火焰图的方法。使用时,使用pyinstrument -r speedscope进行分析,并上传到speedscope网络应用。
• 现在可以使用PYINSTRUMENT_PROFILE_DIR_RENDERER选项为Django中间件文件输出配置渲染器。
• 为Linux aarch64(64位ARM)添加了wheels。

v4.0.4

• 修复了一个打包问题,即在pyinstrument旁边安装了一个名为'test'的包
• 使用更现代的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的错误。

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渲染器上添加了时间线模式支持
• 同时作为tarball和通用wheel发布

v3.1.0

• 在Django中间件上添加了PYINSTRUMENT_SHOW_CALLBACK选项,以添加显示配置文件的条件(可用于在实时服务器上运行pyinstrument!)
• 修复了Django中间件中由于Unicode错误导致文件无法写入的错误

v3.0.3

• 修复了Django中间件在Windows上的错误,其中尝试在配置文件路径中放置非法字符'?'会导致分析失败。(#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。

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

• 组中非常慢的帧也会显示,例如套接字上的'read'调用

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

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

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

    --hide=EXPR           glob样式模式匹配要隐藏的文件路径的帧。
                          默认为'*/lib/*'。
    --hide-regex=REGEX    正则表达式匹配要隐藏的文件路径的帧。
                          当--hide不够控制时很有用。
  

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

    -t, --timeline        渲染为时间线 - 保留顺序并且不压缩重复调用
  

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

• 隐藏的组也可以调用回应用程序代码,看起来像这样:

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

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

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

天哪!详情请见#49。希望你喜欢。

v2.3.0

• 大重构!
  • 移除了Recorders。帧记录现在内置于Profiler对象中。 这意味着'frame'对象更加通用,为以下功能铺平了道路...
  • 处理器!这些是用于改变树结构以塑造输出的函数。 渲染器使用它们将输出过滤成正确的形式。现在,不再使用 时间聚合记录器,分析器只使用时间线式记录(这种方式 开销更低),聚合作为一个处理步骤完成。
  • 这样做的好处是,现在更容易改变树结构来过滤内容,并且 可以做更高级的事情,比如合并我们不关心的帧。v3.0中将会有更多使用这一功能的特性!
• 移除了Importlib帧 - 你将完全看不到它们。它们的子帧被保留,所以 导入是透明的。
• Django配置文件名现在限制为100个字符(#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: # 在这里执行一些工作... print(profiler.output_text())

• 修复了旧版Django的中间件问题

v2.0.2

• 修复了当用于分析堆栈帧很多的程序时出现的最大递归错误。

v2.0.1

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

v2.0.0

• Pyinstrument使用新的分析模式。不再使用 信号,pyinstrument使用基于PyEval_SetProfile构建的新统计分析器。 这意味着不再有主线程限制,使用Pyinstrument时不再有IO错误, 也不需要单独的'setprofile'模式!

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

• 记录器。为了支持Pyinstrument的其他用例(例如火焰图), pyinstrument现在有一个'timeline'记录器模式。这种模式以线性方式记录捕获的 帧,因此可以在时间线上查看程序执行情况。

v0.13

• pyinstrument命令。你现在可以通过运行$ 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

在本地运行代码检查:

pre-commit run --all-files

一些pre-commit检查,如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渲染器通过将样本的JSON表示与 JavaScript"bundle"嵌入到可以在任何Web浏览器中查看的HTML文件中来工作。

要编辑html渲染器样式,请执行以下操作:

cd html_renderer
npm ci
npm run serve

当没有顶级window.profileSession对象启动时,它会 获取一个示例配置文件,以便你可以使用它。

要编译JS应用并将其捆绑回pyinstrument python工具中:

bin/build_js_bundle.py [--force]