PyStack

打印运行中的Python进程或Python核心转储的堆栈跟踪。

PyStack是一个工具，使用禁止的魔法来允许您检查运行中的Python进程或Python核心转储的堆栈帧，帮助您快速轻松地了解它在做什么（或它在崩溃时做了什么），而无需解释恶心的CPython内部结构。

PyStack能做什么

PyStack具有以下惊人的功能

• 💻 适用于运行中的进程和核心转储文件。
• 🧵 显示每个线程是否当前持有Python GIL，正在等待获取它，或正在当前释放它。
• 🗑️ 显示线程是否正在运行垃圾回收周期。
• 🐍 可选地显示原生函数调用，包括Python调用。在此模式下，PyStack打印原生堆栈跟踪（C/C++/Rust函数调用），但将Python可调用对象的调用替换为显示正在执行的Python代码的帧，而不是显示解释器用于执行调用的内部C代码。
• 🔍 自动解混淆原生堆栈中显示的符号。
• 📈 当有足够的调试信息时，包括内联函数的调用。
• 🔍 可选地显示Python堆栈帧中局部变量和函数参数的值。
• 🔒 在运行进程上使用是安全的。PyStack不会修改任何内存或执行任何正在运行的进程中的代码。它只是附着足够长的时间来读取进程的一些内存。
• ⚡ 可选地，它可以在不暂停进程的情况下执行Python堆栈分析。这最大限度地减少了调试进程的影响，但可能会因为数据竞争而失败。
• 🚀 非常快！它分析核心文件的速度比通用工具如GDB快10倍。
• 🎯 即使是经过积极优化的Python解释器二进制文件也能正常工作。
• 🔍 即使是与没有符号或调试信息的Python解释器二进制文件一起工作（仅Python堆栈）。
• 💥 良好地容忍内存损坏。即使进程因内存损坏而崩溃，PyStack通常也能重建堆栈。
• 💼 自包含：它不依赖于运行PyStack本身所使用的Python解释器之外的任何外部工具或程序。

支持哪些平台？

目前只支持Linux。

从源码构建

如果您想从源码构建PyStack，您需要在系统中安装以下二进制依赖项

• libdw
• libelf

注意，有时这两个库作为分发的一部分（如elfutils包）一起提供。

检查您的包管理器以了解如何安装这些依赖项（例如，在基于Debian的系统上apt-get install libdw-dev libelf-dev）。请注意，您可能需要告诉编译器依赖项的头文件和库文件的路径，以便构建成功。如果pkg-config可用（例如，在基于Debian的系统上apt-get install pkg-config），它将自动用于定位库并配置正确的构建标志。检查您的分发文档以确定头文件和库文件的路径，或获取更详细的信息。在Alpine Linux（或任何不使用glibc的其它分发）上构建时，您将需要elfutils 0.188或更新的版本。如果您的分发包管理器中没有它，您可能需要从源码构建。

安装这些二进制依赖项后，您可以克隆存储库并遵循Python库的典型构建过程。

git clone git@github.com:bloomberg/pystack.git pystack
cd pystack
python3 -m venv ../pystack-env/  # just an example, put this wherever you want
source ../pystack-env/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .
python3 -m pip install -r requirements-test.txt -r requirements-extra.txt

这将安装PyStack到开发模式下的虚拟环境（最后一个pip install命令的-e），然后安装测试、lint和生成其文档所需的Python库。

如果您计划贡献，应安装pre-commit钩子

pre-commit install

这将确保您的贡献通过我们的lint检查。

文档

您可以在这里找到完整的文档。

用法

PyStack使用不同的子命令来分析运行中的进程和核心转储文件。

usage: pystack [-h] [-v] [--no-color] {remote,core} ...

Get Python stack trace of a remote process

options:
  -h, --help     show this help message and exit
  -v, --verbose
  --no-color     Deactivate colored output

commands:
  {remote,core}  What should be analyzed by PyStack (use <command> --help for a command-specific help section).
    remote       Analyze a remote process given its PID
    core         Analyze a core dump file given its location and the executable

分析运行中的进程

使用remote命令来分析正在运行（远程）进程的状态。分析始终以安全和侵入性的方式进行，因为不会在分析进程的内存空间中加载代码，也不会修改远程进程中的内存。这使得使用PyStack进行分析成为那些在运行进程必须以任何方式受到影响的（除了临时暂停之外）环境中服务的绝佳选择。有几个选项可用

usage: pystack remote [-h] [-v] [--no-color] [--no-block] [--native] [--native-all] [--locals] [--exhaustive] pid

positional arguments:
  pid            The PID of the remote process

options:
  -h, --help     show this help message and exit
  -v, --verbose
  --no-color     Deactivate colored output
  --no-block     do not block the process when inspecting its memory
  --native       Include the native (C) frames in the resulting stack trace
  --native-all   Include native (C) frames from threads not registered with the interpreter (implies --native)
  --locals       Show local variables for each frame in the stack trace
  --exhaustive   Use all possible methods to obtain the Python stack info (may be slow)

要使用PyStack，您只需要提供进程的PID

$ pystack remote 112
Traceback for thread 112 [] (most recent call last):
    (Python) File "/test.py", line 17, in <module>
        first_func()
    (Python) File "/test.py", line 6, in first_func
        second_func()
    (Python) File "/test.py", line 10, in second_func
        third_func()
    (Python) File "/test.py", line 14, in third_func
        time.sleep(1000)

分析核心转储

《core》子命令用于分析核心转储文件的状态。分析核心文件与分析进程非常相似，但也有一些区别，因为核心文件不包含程序运行时有效的全部内存。在大多数情况下，这并没有什么区别，因为PyStack会自动尝试适应。然而，在某些情况下，您可能需要指定额外的命令行选项，以帮助PyStack定位所需的信息。在分析核心时，有几种选项可供选择。

usage: pystack core [-h] [-v] [--no-color] [--native] [--native-all] [--locals] [--exhaustive] [--lib-search-path LIB_SEARCH_PATH | --lib-search-root LIB_SEARCH_ROOT] core [executable]

positional arguments:
  core                  The path to the core file
  executable            (Optional) The path to the executable of the core file

options:
  -h, --help            show this help message and exit
  -v, --verbose
  --no-color            Deactivate colored output
  --native              Include the native (C) frames in the resulting stack trace
  --native-all          Include native (C) frames from threads not registered with the interpreter (implies --native)
  --locals              Show local variables for each frame in the stack trace
  --exhaustive          Use all possible methods to obtain the Python stack info (may be slow)
  --lib-search-path LIB_SEARCH_PATH
                        List of paths to search for shared libraries loaded in the core. Paths must be separated by the ':' character
  --lib-search-root LIB_SEARCH_ROOT
                        Root directory to search recursively for shared libraries loaded into the core.

在大多数情况下，您只需要提供核心的位置，以便使用PyStack处理核心转储文件。

$ pystack core ./the_core_file
Using executable found in the core file: /usr/bin/python3.8

Core file information:
state: t zombie: True niceness: 0
pid: 570 ppid: 1 sid: 1
uid: 0 gid: 0 pgrp: 570
executable: python3.8 arguments: python3.8

The process died due receiving signal SIGSTOP
Traceback for thread 570 [] (most recent call last):
    (Python) File "/test.py", line 19, in <module>
        first_func({1: None}, [1,2,3])
    (Python) File "/test.py", line 7, in first_func
        second_func(x, y)
    (Python) File "/test.py", line 12, in second_func
        third_func(x, y)
    (Python) File "/test.py", line 16, in third_func
        time.sleep(1000)

许可

PyStack遵循Apache-2.0许可协议，如《LICENSE》文件所示。

行为准则

• 行为准则

本项目已采用行为准则。如果您对准则有任何疑问，或在本项目中经历了任何不当行为，请通过opensource@bloomberg.net与我们联系。

安全策略

• 安全策略

如果您认为您已在此项目中发现安全漏洞，请通过opensource@bloomberg.net将电子邮件发送给项目团队，详细说明可疑问题以及您发现复现问题的任何方法。

请勿在GitHub存储库中打开问题，因为我们希望将漏洞报告保持私密，直到我们有机会审查和解决它们。

贡献

我们欢迎您的贡献，以帮助我们改进和扩展此项目！

以下是一些基本的步骤，以便您能够为本项目做出贡献。如果您对此过程或向Bloomberg开源项目做出贡献的任何其他方面有任何疑问，请随时通过opensource@bloomberg.net发送电子邮件，我们将尽快回答您的问题。

贡献许可

由于本项目根据开源许可协议分发，因此您做出的贡献也将遵循相同的条款。为了能够接受您的贡献，我们需要您明确确认您能够并愿意在这些条款下提供它们，我们用来做到这一点的方法称为开发者原创性证书（DCO）。这与Linux内核、Samba和其他许多主要开源项目所使用的流程类似。

要遵守这些条款进行参与，您必须做的只是在每个贡献的提交消息的最后一行包含以下类似的行

Signed-Off-By: Random J. Developer <random@developer.example.org>

完成此操作的最简单方法是向您的git commit命令添加-s或--signoff。

您必须使用您的真实姓名（抱歉，不接受化名，也不接受匿名贡献）。

步骤

• 创建一个问题，选择“功能请求”，并解释所提出的更改。
• 遵循您面前的问题模板中的指南。
• 提交问题。
• 提交拉取请求，并在拉取请求摘要中包含“#”以将其链接到问题。