<p align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/1272b091-2164-442a-a913-3ffc64d6cbf2.png" width="70%"> </p>

---

PyStack

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

PyStack是一个使用禁忌魔法的工具，可以让你检查正在运行的Python进程或Python核心转储的堆栈帧，帮助你快速轻松地了解它正在做什么（或崩溃时正在做什么），而无需解释复杂的CPython内部结构。

PyStack的功能

PyStack具有以下惊人的特性：

• 💻 适用于运行中的进程和核心转储文件。
• 🧵 显示每个线程当前是否持有Python GIL、正在等待获取GIL，或正在释放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/  # 只是一个例子，你可以把它放在任何地方
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} ...

获取远程进程的Python堆栈跟踪

选项：
  -h, --help     显示此帮助消息并退出
  -v, --verbose
  --no-color     停用彩色输出

命令：
  {remote,core}  PyStack应分析的对象（使用<command> --help获取特定命令的帮助部分）。
    remote       分析给定PID的远程进程
    core         分析给定位置的核心转储文件和可执行文件

分析运行中的进程

remote命令用于分析运行中（远程）进程的状态。分析总是以安全和非侵入性的方式进行，因为没有代码被加载到被分析进程的内存空间中，也没有修改远程进程中的内存。这使得使用PyStack进行分析成为那些在不能以任何方式影响运行进程的环境中运行的服务和应用程序的绝佳选择（除了暂时暂停之外，尽管--no-block可以避免这一点）。有几个可用选项：

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

位置参数：
  pid            远程进程的PID

选项：
  -h, --help     显示此帮助消息并退出
  -v, --verbose
  --no-color     停用彩色输出
  --no-block     检查内存时不阻塞进程
  --native       在结果堆栈跟踪中包含原生（C）帧
  --native-all   包含未在解释器中注册的线程的原生（C）帧（隐含--native）
  --locals       显示堆栈跟踪中每个帧的局部变量
  --exhaustive   使用所有可能的方法获取Python堆栈信息（可能会很慢）

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

$ pystack remote 112
线程112的回溯 [] （最近的调用最后）：
    (Python) 文件 "/test.py"，第17行，在 <module>
        first_func()
    (Python) 文件 "/test.py"，第6行，在 first_func
        second_func()
    (Python) 文件 "/test.py"，第10行，在 second_func
        third_func()
    (Python) 文件 "/test.py"，第14行，在 third_func
        time.sleep(1000)

分析核心转储

core 子命令用于分析核心转储文件的状态。分析核心文件与分析进程非常相似，但存在一些差异，因为核心文件并不包含程序运行时所有有效的内存。在大多数情况下，这并不会造成影响，因为PyStack会自动尝试适应。然而，在某些情况下，你需要指定额外的命令行选项来帮助PyStack定位所需的信息。在分析核心文件时，有以下几个可用选项：

用法: 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]

位置参数:
  core                  核心文件的路径
  executable            （可选）核心文件对应的可执行文件路径

选项:
  -h, --help            显示此帮助信息并退出
  -v, --verbose
  --no-color            禁用彩色输出
  --native              在结果堆栈跟踪中包含原生（C）帧
  --native-all          包含未在解释器中注册的线程的原生（C）帧（包含--native）
  --locals              显示堆栈跟踪中每个帧的局部变量
  --exhaustive          使用所有可能的方法获取Python堆栈信息（可能会很慢）
  --lib-search-path LIB_SEARCH_PATH
                        搜索核心中加载的共享库的路径列表。路径必须用':'字符分隔
  --lib-search-root LIB_SEARCH_ROOT
                        递归搜索核心中加载的共享库的根目录

在大多数情况下，你只需要提供核心文件的位置即可使用PyStack处理核心转储文件：

$ pystack core ./the_core_file
使用核心文件中找到的可执行文件：/usr/bin/python3.8

核心文件信息：
状态：t 僵尸进程：True 优先级：0
进程ID：570 父进程ID：1 会话ID：1
用户ID：0 组ID：0 进程组：570
可执行文件：python3.8 参数：python3.8

进程因接收到SIGSTOP信号而终止
线程570 []的回溯（最近的调用在最后）：
    （Python）文件"/test.py"，第19行，在<module>中
        first_func({1: None}, [1,2,3])
    （Python）文件"/test.py"，第7行，在first_func中
        second_func(x, y)
    （Python）文件"/test.py"，第12行，在second_func中
        third_func(x, y)
    （Python）文件"/test.py"，第16行，在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。

你必须使用你的真实姓名（抱歉，不允许使用假名，也不允许匿名贡献）。

步骤

• 创建一个Issue，选择"功能请求"，并解释提议的更改。
• 遵循向你展示的issue模板中的指南。
• 提交Issue。
• 提交Pull Request并通过在Pull Request摘要中包含"#<issue编号>"将其链接到Issue。