PyPI - Python 版本 PyPI - 实现 PyPI PyPI - 下载量代码风格

Memray 是一个 Python 内存分析器。它可以跟踪 Python 代码、原生扩展模块和 Python 解释器本身中的内存分配。它可以生成几种不同类型的报告，帮助您分析捕获的内存使用数据。虽然通常作为命令行工具使用，但它也可以作为库来执行更精细的分析任务。

主要特点：

🕵️‍♀️ 跟踪每个函数调用，因此可以准确表示调用栈，这是采样分析器所不具备的。
ℭ 还处理 C/C++ 库中的原生调用，因此结果中包含完整的调用栈。
🏎 速度极快！分析仅会略微减慢应用程序。跟踪原生代码稍慢一些，但可以按需启用或禁用。
📈 可以生成关于收集到的内存使用数据的各种报告，如火焰图。
🧵 支持 Python 线程。
👽🧵 支持原生线程（例如 C 扩展中的 C++ 线程）。

Memray 可以帮助解决以下问题：

分析应用程序中的内存分配，帮助发现高内存使用的原因。
查找内存泄漏。
查找导致大量内存分配的代码热点。

注意 Memray 仅适用于 Linux 和 MacOS，无法在其他平台上安装。

帮助我们改进 Memray！

我们一直在寻求来自我们出色社区的反馈❤️。如果您使用 Memray 解决了问题、分析了应用程序、找到了内存泄漏或做了其他任何事情，请告诉我们！我们很想听听您的经历以及 Memray 如何帮助到您。

请考虑在成功案例讨论页面上分享您的故事。

这真的会产生很大的影响！

安装

Memray 需要 Python 3.7+ 版本，可以使用大多数常见的 Python 打包工具轻松安装。我们建议使用 pip 从 PyPI 安装最新的稳定版本：

    python3 -m pip install memray

请注意，Memray 包含一个 C 扩展，因此发布版本以二进制轮子和源代码的形式分发。如果您的系统（Linux x86/x64 或 macOS）没有可用的二进制轮子，您需要确保在安装的系统上满足所有依赖项。

从源代码构建

如果您希望从源代码构建 Memray，您的系统需要以下二进制依赖项：

libdebuginfod-dev（适用于 Linux）
libunwind（适用于 Linux）
liblz4

请查看您的包管理器以了解如何安装这些依赖项（例如，在基于 Debian 的系统上使用 apt-get install build-essential python3-dev libdebuginfod-dev libunwind-dev liblz4-dev，或在 MacOS 上使用 brew install lz4）。请注意，您可能需要告诉编译器在哪里找到依赖项的头文件和库文件。例如，在使用 brew 的 MacOS 上，您可能需要在安装 memray 之前运行：

export CFLAGS="-I$(brew --prefix lz4)/include" LDFLAGS="-L$(brew --prefix lz4)/lib -Wl,-rpath,$(brew --prefix lz4)/lib"

请查看您的包管理器文档，以了解有关头文件和库文件位置的更详细信息。

如果您在 MacOS 上构建，还需要设置部署目标。

export MACOSX_DEPLOYMENT_TARGET=10.14

安装好二进制依赖项后，您可以克隆仓库并按照正常的构建过程进行：

git clone git@github.com:bloomberg/memray.git memray
cd memray
python3 -m venv ../memray-env/  # 只是一个例子，您可以将其放在任何地方
source ../memray-env/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e . -r requirements-test.txt -r requirements-extra.txt

这将以开发模式将 Memray 安装到虚拟环境中（最后一个 pip install 命令中的 -e）。

如果您计划贡献代码，应该安装预提交钩子：

pre-commit install

这将确保您的贡献通过我们的代码风格检查。

文档

您可以在这里找到最新的文档。

使用方法

使用 Memray 有多种方式。最简单的方法是将其作为命令行工具来运行您的脚本、应用程序或库。

用法：memray [-h] [-v] {run,flamegraph,table,live,tree,parse,summary,stats} ...

Python 应用程序的内存分析器

运行 `memray run` 生成内存分析报告，然后使用报告器命令
如 `memray flamegraph` 或 `memray table` 将结果转换为 HTML。

示例：

    $ python3 -m memray run -o output.bin my_script.py
    $ python3 -m memray flamegraph output.bin

位置参数：
  {run,flamegraph,table,live,tree,parse,summary,stats}
                        操作模式
    run                 运行指定的应用程序并跟踪内存使用情况
    flamegraph          为峰值内存使用情况生成 HTML 火焰图
    table               为峰值内存使用情况中的所有记录生成 HTML 表格
    live                通过基于文本的界面远程监控内存分配
    tree                为峰值内存使用情况在终端生成树形视图
    parse               通过解析并打印结果文件中的每条记录来调试
    summary             生成基于终端的摘要报告，显示分配最多内存的函数
    stats               在终端中生成内存使用情况的高级统计信息

可选参数：
  -h, --help            显示此帮助信息并退出
  -v, --verbose         增加详细程度。选项可累加，最多可指定 3 次
  -V, --version         显示 Memray 的当前版本

请通过在 https://github.com/bloomberg/memray/issues 提交新议题来提供反馈、想法和错误报告

要对脚本或单个 Python 文件使用 Memray，可以使用：

python3 -m memray run my_script.py

如果您通常使用 python3 -m my_module 运行应用程序，可以在 memray run 中使用 -m 标志：

python3 -m memray run -m my_module

您也可以将 Memray 作为命令行工具直接调用，无需使用 -m 来调用模块：

memray run my_script.py
memray run -m my_module

输出将是一个二进制文件（如 memray-my_script.2369.bin），您可以通过不同方式分析它。一种方法是使用 memray flamegraph 命令生成火焰图：

memray flamegraph my_script.2369.bin

这将生成一个包含内存使用情况火焰图的 HTML 文件，您可以使用喜欢的浏览器查看。还有多个其他报告器可用于生成其他类型的报告，有些生成基于终端的输出，有些生成 HTML 文件。以下是 Memray 火焰图的示例：

Pytest 插件

如果您想在测试套件中方便地使用 memray，可以考虑使用 pytest-memray。安装后，这个 pytest 插件允许您只需在命令行调用中添加 --memray：

pytest --memray tests/

这将自动获得如下报告：

python3 -m pytest tests --memray
=============================================================================================================================== test session starts ================================================================================================================================
platform linux -- Python 3.8.10, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
rootdir: /mypackage, configfile: pytest.ini
plugins: cov-2.12.0, memray-0.1.0
collected 21 items

tests/test_package.py .....................                                                                                                                                                                                                                      [100%]


================================================================================================================================= MEMRAY REPORT ==================================================================================================================================
Allocations results for tests/test_package.py::some_test_that_allocates

	 📦 总分配内存：24.4MiB
	 📏 总分配次数：33929
	 📊 分配大小直方图：|▂   █    |
	 🥇 分配最多内存的函数：
		- parse:/opt/bb/lib/python3.8/ast.py:47 -> 3.0MiB
		- parse:/opt/bb/lib/python3.8/ast.py:47 -> 2.3MiB
		- _visit:/opt/bb/lib/python3.8/site-packages/astroid/transforms.py:62 -> 576.0KiB
		- parse:/opt/bb/lib/python3.8/ast.py:47 -> 517.6KiB
		- __init__:/opt/bb/lib/python3.8/site-packages/astroid/node_classes.py:1353 -> 512.0KiB

您还可以使用一些内置的标记，使测试在执行时分配的内存超过允许的限制时失败：

@pytest.mark.limit_memory("24 MB")
def test_foobar():
    # 执行一些分配内存的操作

要了解更多关于如何使用和配置插件的信息，请查看插件文档。

原生模式

Memray 支持跟踪原生 C/C++ 函数和 Python 函数。这在分析具有 C 扩展的应用程序（如 numpy 或 pandas）时特别有用，因为它提供了扩展分配的内存和 Python 本身分配的内存的整体视图。

要激活原生跟踪，您需要在使用 run 子命令时提供 --native 参数：

memray run --native my_script.py

这将自动向结果文件添加原生信息，并且会被任何报告器（如火焰图或表格报告器）自动使用。这意味着在火焰图中，你将不再看到这样的内容：

现在你将能够看到Python调用内部发生的情况：

报告器以不同于Python帧的颜色显示原生帧。也可以通过查看帧中的文件位置来区分它们（Python帧通常由扩展名为.py的文件生成，而原生帧则由扩展名为.c、.cpp或.h的文件生成）。

实时模式

Memray的实时模式在基于终端的界面中运行脚本或模块，允许你在运行时交互式地检查其内存使用情况。这对于调试长时间运行或展现多个复杂内存模式的脚本或模块非常有用。你可以使用--live选项在实时模式下运行脚本或模块：

    memray run --live my_script.py

或者如果你想执行一个模块：

    memray run --live -m my_module

这将在你的终端中显示以下TUI界面：

排序结果

结果按函数及其调用的子函数分配的总内存量降序显示。你可以使用以下键盘快捷键更改排序方式：

t（默认）：按总内存排序
o：按自身内存排序
a：按分配次数排序

在大多数终端中，你还可以点击页脚上的"Sort by Total"、"Sort by Own"和"Sort by Allocations"按钮。

排序列的标题会被下划线标记。

查看不同线程

默认情况下，live命令将展示程序的主线程。你可以通过按大于和小于键（<和>）来查看程序的不同线程。在大多数终端中，你还可以点击页脚上的"Previous Thread"和"Next Thread"按钮。

API

除了使用memray run从CLI跟踪Python进程外，还可以在运行中的Python程序内以编程方式启用跟踪。

import memray

with memray.Tracker("output_file.bin"):
    print("在with块结束之前，分配将被跟踪")

详细信息请参阅API文档。

许可证

Memray采用Apache-2.0许可证，详见LICENSE文件。

行为准则

行为准则

本项目已采用行为准则。如果你对准则有任何疑虑，或在项目中遇到任何行为问题，请通过opensource@bloomberg.net与我们联系。

安全策略

安全策略

如果你认为在本项目中发现了安全漏洞，请发送电子邮件至opensource@bloomberg.net，详细说明可疑问题以及你发现的任何重现方法。

请不要在GitHub仓库中公开提出问题，因为我们更希望在有机会审查和解决漏洞之前将其保密。

贡献

我们欢迎你的贡献，以帮助我们改进和扩展这个项目！

以下是能够为项目做出贡献所需的一些基本步骤。如果你对这个过程或为彭博开源项目做出贡献的任何其他方面有任何问题，请随时发送电子邮件至opensource@bloomberg.net，我们将尽快回答你的问题。

贡献许可

由于本项目是根据开源许可证条款分发的，你做出的贡献也将在相同条款下获得许可。为了使我们能够接受你的贡献，我们需要你明确确认你能够并愿意根据这些条款提供贡献，我们用来实现这一点的机制称为开发者原创证书(DCO)。这与Linux内核、Samba和许多其他主要开源项目使用的过程非常相似。

要在这些条款下参与，你只需要在贡献中每个提交的提交消息的最后一行包含如下内容：

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

实现这一点的最简单方法是在你的git commit命令中添加-s或--signoff。

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

步骤

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

memray

帮助我们改进 Memray！

安装

从源代码构建

文档

使用方法

Pytest 插件

原生模式

实时模式

排序结果

查看不同线程

API

许可证

行为准则

安全策略

贡献

贡献许可

步骤

编辑推荐精选

Keevx

即梦AI

扣子-AI办公

TRAE编程

蛙蛙写作

问小白

Transly

讯飞智文

讯飞星火

Spark-TTS

探索AI的无限可能

推荐工具精选

TRAE编程

扣子-AI办公

讯飞文书

讯飞绘文

讯飞绘镜

阿里绘蛙

咔片PPT

AI云服务特惠

火山引擎

阿里云

腾讯云

华为云

百度智能云

AWS

关注微信公众号