.. image:: https://travis-ci.org/pythonprofilers/memory_profiler.svg?branch=master :target: https://travis-ci.org/pythonprofilers/memory_profiler

================= 内存分析器

注意: 该软件包不再积极维护。我不会积极回应问题。

这是一个用于监控进程内存消耗以及对Python程序进行逐行内存消耗分析的Python模块。它是一个纯Python模块，依赖于psutil <http://pypi.python.org/pypi/psutil>_模块。

============== 安装

通过pip安装::

$ pip install -U memory_profiler

该软件包也可在conda-forge <https://github.com/conda-forge/memory_profiler-feedstock>_上获得。

要从源代码安装，下载软件包，解压后输入::

$ pip install .

=========== 快速入门

使用mprof生成可执行文件的完整内存使用报告并绘图。

.. code-block:: bash

mprof run executable
mprof plot

图表将类似于这样:

.. image:: https://i.stack.imgur.com/ixCH4.png

======= 使用

逐行内存使用

逐行内存使用模式的使用方式与line_profiler <https://pypi.python.org/pypi/line_profiler/>_非常相似:首先用@profile装饰器装饰你想要分析的函数,然后用特殊脚本运行脚本(在这种情况下,使用Python解释器的特定参数)。

在下面的例子中,我们创建了一个简单的函数my_func,它分配列表a、b,然后删除b:

.. code-block:: python

@profile
def my_func():
    a = [1] * (10 ** 6)
    b = [2] * (2 * 10 ** 7)
    del b
    return a

if __name__ == '__main__':
    my_func()

执行代码时,向Python解释器传递选项-m memory_profiler以加载memory_profiler模块并将逐行分析打印到stdout。如果文件名是example.py,结果将是::

$ python -m memory_profiler example.py

输出如下::

Line #    Mem usage    Increment  Occurrences   Line Contents
============================================================
     3   38.816 MiB   38.816 MiB           1   @profile
     4                                         def my_func():
     5   46.492 MiB    7.676 MiB           1       a = [1] * (10 ** 6)
     6  199.117 MiB  152.625 MiB           1       b = [2] * (2 * 10 ** 7)
     7   46.629 MiB -152.488 MiB           1       del b
     8   46.629 MiB    0.000 MiB           1       return a

第一列代表已分析代码的行号,第二列(Mem usage)表示该行执行后Python解释器的内存使用情况。第三列(Increment)表示当前行相对于上一行的内存差异。第四列(Occurrences)显示分析器执行每行的次数。最后一列(Line Contents)打印已分析的代码。

装饰器

还提供了一个函数装饰器。使用方法如下:

.. code-block:: python

from memory_profiler import profile

@profile
def my_func():
    a = [1] * (10 ** 6)
    b = [2] * (2 * 10 ** 7)
    del b
    return a

在这种情况下,可以在命令行中不指定-m memory_profiler运行脚本。

在函数装饰器中,你可以将精度指定为装饰器函数的参数。使用方法如下:

.. code-block:: python

from memory_profiler import profile

@profile(precision=4)
def my_func():
    a = [1] * (10 ** 6)
    b = [2] * (2 * 10 ** 7)
    del b
    return a

如果使用-m memory_profiler在命令行中调用带有装饰器@profile的Python脚本,则忽略precision参数。

基于时间的内存使用

有时,获得外部进程(无论是Python脚本还是其他)随时间变化的完整内存使用报告会很有用。在这种情况下,可执行文件mprof可能会有帮助。使用方法如下::

mprof run <executable>
mprof plot

第一行运行可执行文件并记录随时间变化的内存使用情况,将结果写入当前目录的文件中。 完成后,可以使用第二行获得图形绘制。 记录的文件包含时间戳,允许同时保存多个配置文件。

可以使用-h标志获取每个mprof子命令的帮助, 例如mprof run -h。

对于Python脚本,使用上述命令不会 提供任何关于在给定时间执行哪个函数的信息。根据具体情况,可能很难确定 导致最高内存使用的代码部分。

向函数添加profile装饰器(确保没有 from memory_profiler import profile语句)并运行Python 脚本:

mprof run --python python <script>

将记录进入/离开被分析函数的时间戳。之后运行

mprof plot

将绘制结果,生成类似于以下的图表(使用matplotlib):

.. image:: https://camo.githubusercontent.com/3a584c7cfbae38c9220a755aa21b5ef926c1031d/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313930383631382f3836313332302f63623865376337382d663563632d313165322d386531652d3539373237623636663462322e706e67 :target: https://github.com/scikit-learn/scikit-learn/pull/2248 :height: 350px

或者,使用mprof plot --flame(函数和时间戳名称将在悬停时显示):

.. image:: ./images/flamegraph.png :height: 350px

关于这些功能的讨论可以在这里 <http://fa.bianp.net/blog/2014/plot-memory-usage-as-a-function-of-time/>_找到。

.. warning:: 如果你的Python文件导入了内存分析器from memory_profiler import profile,这些时间戳将不会被记录。注释掉导入,保留装饰的函数,然后重新运行。

mprof可用的命令有:

• mprof run: 运行可执行文件,记录内存使用情况
• mprof plot: 绘制记录的内存使用情况(默认为最后一个)
• mprof list: 以用户友好的方式列出所有记录的内存使用文件
• mprof clean: 删除所有记录的内存使用文件
• mprof rm: 删除特定的记录内存使用文件

跟踪分叉的子进程

在多进程环境中,主进程将产生子进程,其系统资源与父进程分开分配。这可能导致内存使用报告不准确,因为默认情况下只跟踪父进程。mprof工具提供了两种机制来跟踪子进程的使用情况:将所有子进程的内存加到父进程的使用量中,以及单独跟踪每个子进程。

要创建一个合并所有子进程和父进程内存使用的报告,在profile装饰器中或作为mprof的命令行参数使用include-children标志::

mprof run --include-children <script>

第二种方法独立于主进程跟踪每个子进程, 将子行按索引序列化到输出流。使用multiprocess 标志并按如下方式绘图::

mprof run --multiprocess <script>
mprof plot

这将使用matplotlib创建一个类似于这样的图: .. image:: https://cloud.githubusercontent.com/assets/745966/24075879/2e85b43a-0bfa-11e7-8dfe-654320dbd2ce.png :target: https://github.com/pythonprofilers/memory_profiler/pull/134 :height: 350px

你可以同时使用 include-children 和 multiprocess 标志来显示程序的总内存以及每个子进程的单独内存。如果直接使用API，请注意 memory_usage 的返回值将包含主进程内存和嵌套列表形式的子进程内存。

绘图设置

默认情况下，命令行调用会被设置为图表标题。如果你想自定义它，可以使用 -t 选项手动设置图表标题。

mprof plot -t '记录的内存使用情况'

你也可以使用 n 标志隐藏函数时间戳，例如：

mprof plot -n

可以使用 s 标志绘制趋势线及其数值斜率，例如：

mprof plot -s

.. image:: ./images/trend_slope.png :height: 350px

-s 开关的预期用途是在较长时间段内检查标签的数值斜率：

• >0 可能意味着内存泄漏。
• ~0 如果为0或接近0，可以认为内存使用稳定。
• <0 需要根据预期的进程内存使用模式来解释，也可能意味着采样周期太小。

趋势线仅用于说明目的，以(非常)小的虚线绘制。

设置调试器断点

可以根据使用的内存量设置断点。 也就是说，你可以指定一个阈值，一旦程序使用的内存超过指定的阈值， 它将停止执行并进入pdb调试器。要使用它，你需要像前面章节那样用 @profile 装饰函数， 然后使用 -m memory_profiler --pdb-mmem=X 选项运行脚本， 其中X是一个表示内存阈值(MB)的数字。例如：

$ python -m memory_profiler --pdb-mmem=100 my_script.py

这将运行 my_script.py，一旦装饰函数中的代码使用超过100 MB内存，就会进入pdb调试器。

.. TODO: 装饰的替代方法(例如当你不想修改函数所在的文件时)。

===== API

memory_profiler 提供了一些可在第三方代码中使用的函数。

memory_usage(proc=-1, interval=.1, timeout=None) 返回一段时间内的内存使用情况。第一个参数 proc 表示要监控的对象。这可以是进程的PID(不一定是Python程序)、包含要评估的Python代码的字符串，或包含函数及其参数的元组 (f, args, kw)，将作为 f(*args, **kw) 进行评估。例如，

.. code-block:: python

>>> from memory_profiler import memory_usage
>>> mem_usage = memory_usage(-1, interval=.2, timeout=1)
>>> print(mem_usage)
[7.296875, 7.296875, 7.296875, 7.296875, 7.296875]

这里我让memory_profiler在1秒内以0.2秒的时间间隔获取当前进程的内存消耗。PID我给的是-1，这是一个特殊数字(PID通常是正数)，表示当前进程，即我正在获取当前Python解释器的内存使用情况。因此，我从一个普通的Python解释器中获得了大约7MB的内存使用量。如果我在IPython(控制台)上尝试相同的操作，会得到29MB，如果在IPython notebook上尝试，则会增加到44MB。

如果你想获取Python函数的内存消耗，那么你应该在元组 (f, args, kw) 中指定函数及其参数。例如：

.. code-block:: python

>>> # 定义一个简单的函数
>>> def f(a, n=100):
    ...     import time
    ...     time.sleep(2)
    ...     b = [a] * n
    ...     time.sleep(1)
    ...     return b
    ...
>>> from memory_profiler import memory_usage
>>> memory_usage((f, (1,), {'n' : int(1e6)}))

这将执行代码 f(1, n=int(1e6)) 并返回执行期间的内存消耗。

========= 报告

可以通过将IO流作为参数传递给装饰器来将输出重定向到日志文件，如 @profile(stream=fp)

.. code-block:: python

>>> fp=open('memory_profiler.log','w+')
>>> @profile(stream=fp)
>>> def my_func():
    ...     a = [1] * (10 ** 6)
    ...     b = [2] * (2 * 10 ** 7)
    ...     del b
    ...     return a

详情请参考：examples/reporting_file.py

通过logger模块报告:

有时使用logger模块会非常方便，特别是当我们需要使用RotatingFileHandler时。

只需使用memory profiler模块的LogFile，就可以将输出重定向到logger模块。

.. code-block:: python

>>> from memory_profiler import LogFile
>>> import sys
>>> sys.stdout = LogFile('memory_profile_log')

自定义报告:

运行memory_profiler时将所有内容发送到日志文件可能会很麻烦，可以通过向LogFile类的reportIncrementFlag参数传递True来选择只记录有增量的条目，其中reportIncrementFlag是memory profiler模块LogFile类的一个参数。

.. code-block:: python

>>> from memory_profiler import LogFile
>>> import sys
>>> sys.stdout = LogFile('memory_profile_log', reportIncrementFlag=False)

详情请参考：examples/reporting_logger.py

===================== IPython集成

安装模块后，如果你使用IPython，你可以使用 %mprun、%%mprun、%memit 和 %%memit 魔法命令。

对于IPython 0.11+，你可以直接将模块作为扩展使用，使用 %load_ext memory_profiler

要在每次启动IPython时激活它，编辑IPython配置文件 ~/.ipython/profile_default/ipython_config.py，注册扩展如下(如果你已经有其他扩展，只需将这个添加到列表中)：

.. code-block:: python

c.InteractiveShellApp.extensions = [
    'memory_profiler',
]

(如果配置文件不存在，在终端运行 ipython profile create)

然后可以直接在IPython中使用 %mprun 或 %%mprun 魔法命令获取逐行报告。在这种情况下，你可以跳过 @profile 装饰器，而使用 -f 参数，如下所示。但是请注意，函数my_func必须定义在文件中(不能在Python解释器中交互定义)：

.. code-block:: python

In [1]: from example import my_func, my_func_2

In [2]: %mprun -f my_func my_func()

或在单元模式下：

.. code-block:: python

In [3]: %%mprun -f my_func -f my_func_2
   ...: my_func()
   ...: my_func_2()

我们定义的另一个有用的魔法命令是 %memit，它类似于 %timeit。可以这样使用：

.. code-block:: python

In [1]: %memit range(10000)
峰值内存: 21.42 MiB, 增量: 0.41 MiB

In [2]: %memit range(1000000)
峰值内存: 52.10 MiB, 增量: 31.08 MiB

或在单元模式下(带有设置代码)：

.. code-block:: python

In [3]: %%memit l=range(1000000)
   ...: len(l)
   ...:
峰值内存: 52.14 MiB, 增量: 0.08 MiB

有关更多详细信息，请参阅魔术方法的文档字符串。

对于 IPython 0.10，您可以通过编辑 IPython 配置文件 ~/.ipython/ipy_user_conf.py 来安装它，添加以下几行：

.. code-block:: python

# 这两行是标准的，可能已经存在。
import IPython.ipapi
ip = IPython.ipapi.get()

# 这两行是重要的。
import memory_profiler
memory_profiler.load_ipython_extension(ip)

=============================== 内存跟踪后端

memory_profiler 支持不同的内存跟踪后端，包括：'psutil'、'psutil_pss'、'psutil_uss'、'posix'、'tracemalloc'。 如果没有指定特定后端，默认使用 "psutil"，它测量 RSS（即"常驻集大小"）。 在某些情况下（特别是在跟踪子进程时），RSS 可能会高估内存使用量（请参见 example/example_psutil_memory_full_info.py 示例）。 有关 "psutil_pss"（测量 PSS）和 "psutil_uss" 的更多信息，请参阅： https://psutil.readthedocs.io/en/latest/index.html?highlight=memory_info#psutil.Process.memory_full_info

目前，可以通过命令行界面设置后端

$ python -m memory_profiler --backend psutil my_script.py

并通过 API 公开

.. code-block:: python

>>> from memory_profiler import memory_usage
>>> mem_usage = memory_usage(-1, interval=.2, timeout=1, backend="psutil")

============================ 常见问题

* 问：结果有多准确？
* 答：此模块通过查询操作系统内核获取内存消耗，了解当前进程分配的内存量，这可能与 Python 解释器实际使用的内存量略有不同。此外，由于 Python 垃圾收集器的工作方式，结果可能在不同平台甚至不同运行之间有所不同。

* 问：它在 Windows 下工作吗？
* 答：是的，这要感谢 `psutil <http://pypi.python.org/pypi/psutil>`_ 模块。

=========================== 支持、错误和愿望列表

如需支持，请在 stack overflow <http://stackoverflow.com/>_ 上提问，并添加 *memory-profiling* 标签 <http://stackoverflow.com/questions/tagged/memory-profiling>。 将问题、建议等发送到 GitHub 的问题跟踪器 <https://github.com/pythonprofilers/memory_profiler/issues>。

如果您有关于开发的问题，可以直接发送电子邮件至 f@bianp.net

.. image:: http://fa.bianp.net/static/tux_memory_small.png

============= 开发

最新源代码可在 GitHub 上获取：

https://github.com/pythonprofilers/memory_profiler

=============================== 使用 memory_profiler 的项目

Benchy <https://github.com/python-recsys/benchy>_

IPython memory usage <https://github.com/ianozsvald/ipython_memory_usage>_

PySpeedIT <https://github.com/peter1000/PySpeedIT>_（使用 memory_profiler 的简化版本）

pydio-sync <https://github.com/pydio/pydio-sync>_（在 memory_profiler 之上使用自定义包装器）

========= 作者

此模块由 Fabian Pedregosa <http://fseoane.net>_ 和 Philippe Gervais <https://github.com/pgervais>_ 编写， 灵感来自 Robert Kern 的 line profiler <http://packages.python.org/line_profiler/>_。

Tom <http://tomforb.es/>_ 通过 psutil <http://pypi.python.org/pypi/psutil>_ 模块添加了 Windows 支持和速度改进。

Victor <https://github.com/octavo>_ 添加了 Python3 支持、错误修复和总体清理。

Vlad Niculae <http://vene.ro/>_ 添加了 %mprun 和 %memit IPython 魔术方法。

Thomas Kluyver <https://github.com/takluyver>_ 添加了 IPython 扩展。

Sagar UDAY KUMAR <https://github.com/sagaru>_ 添加了报告生成功能和示例。

Dmitriy Novozhilov <https://github.com/demiurg906>_ 和 Sergei Lebedev <https://github.com/superbobry>_ 添加了对 tracemalloc <https://docs.python.org/3/library/tracemalloc.html>_ 的支持。

Benjamin Bengfort <https://github.com/bbengfort>_ 添加了跟踪单个子进程使用情况和绘图的支持。

Muhammad Haseeb Tariq <https://github.com/mhaseebtariq>_ 修复了问题 #152，该问题导致整个解释器在引发异常的函数上挂起。

Juan Luis Cano <https://github.com/Juanlu001>_ 更新了基础设施并帮助解决了各种问题。

Martin Becker <https://github.com/mgbckr>_ 通过 psutil 后端添加了 PSS 和 USS 跟踪。

========= 许可证

BSD 许可证，完整文本请参见 COPYING 文件。