Memray Comandos

Memray é um perfilador de memória para Python desenvolvido pela Bloomberg. Rastreia cada alocação de memória em código Python e extensões C/C++, fornecendo insights detalhados sobre uso de memória através de gráficos de chama, tabelas e rastreamento em tempo real.

Instalação

Linux/Ubuntu

# Install via pip (Linux only — Memray does not support macOS or Windows)
pip install memray

# Install with all optional dependencies
pip install memray[all]

# Install development version
pip install git+https://github.com/bloomberg/memray.git

# Verify installation
memray --version

memray run — Recording Allocations

# Profile a Python script
memray run my_script.py

# Profile with arguments
memray run my_script.py --arg1 --arg2 value

# Profile a module
memray run -m pytest tests/

# Custom output file
memray run -o my_profile.bin my_script.py

# Track native (C/C++) allocations
memray run --native my_script.py

# Follow child processes (fork/exec)
memray run --follow-fork my_script.py

# Trace Python allocators only (faster, less detail)
memray run --trace-python-allocators my_script.py

# Force overwrite existing output file
memray run --force -o profile.bin my_script.py

# Profile with a maximum memory threshold (aggregate mode)
memray run --aggregate my_script.py

memray flamegraph — Gráficos de Chama de Memória

# Generate an HTML flame graph from a recording
memray flamegraph my_profile.bin

# Custom output file
memray flamegraph -o memory_flamegraph.html my_profile.bin

# Show temporary allocations (freed during profiling)
memray flamegraph --temporary-allocations my_profile.bin

# Show only allocations larger than a threshold
memray flamegraph --temporary-allocation-threshold 1024 my_profile.bin

# Filter to leaks only (allocations never freed)
memray flamegraph --leaks my_profile.bin

# Merge threads into a single view
memray flamegraph --merge-threads my_profile.bin

memray table — Relatório Tabular

# Generate an HTML table of allocations
memray table my_profile.bin

# Custom output file
memray table -o allocation_table.html my_profile.bin

# Show temporary allocations
memray table --temporary-allocations my_profile.bin

# Show only leaked allocations
memray table --leaks my_profile.bin

memray tree — Árvore de Chamadas

# Generate a call tree report
memray tree my_profile.bin

# Show largest allocations first
memray tree --biggest-allocs 20 my_profile.bin

# Show temporary allocations
memray tree --temporary-allocations my_profile.bin

memray summary — Resumo de Alocações

# Show a high-level summary of allocations
memray summary my_profile.bin

memray stats — Estatísticas Detalhadas

# Show detailed allocation statistics
memray stats my_profile.bin

# Output includes:
# - Total allocations and deallocations
# - Peak memory usage
# - Allocator breakdown (malloc, calloc, realloc, etc.)
# - Top allocation locations
# - Memory timeline

Modo de Rastreamento ao Vivo

# Start a live tracking session (real-time TUI)
memray run --live my_script.py

# Live tracking with remote connection
# Terminal 1: Start the profiled process
memray run --live-remote --live-port 12345 my_script.py

# Terminal 2: Connect to the live session
memray live 12345

# Live tracking of a module
memray run --live -m flask run

Rastreamento de Alocações Nativas

# Track allocations from C/C++ extensions (numpy, pandas, etc.)
memray run --native my_script.py

# Generate flame graph showing native frames
memray flamegraph my_profile.bin
# Native frames appear in the flame graph alongside Python frames

# Native tracking is essential for:
# - NumPy/SciPy memory usage
# - Pandas DataFrame allocations
# - C extension memory leaks
# - Cython module allocations

Detecção de Vazamentos

# Record and find leaks
memray run -o leak_check.bin my_script.py

# Generate leak-only flame graph
memray flamegraph --leaks leak_check.bin -o leaks.html

# Generate leak-only table
memray table --leaks leak_check.bin -o leaks_table.html

# Generate leak-only tree view
memray tree --leaks leak_check.bin

Plugin pytest

# Install memray pytest plugin (included with memray)
pip install memray

# Run tests with memory limit enforcement
pytest --memray tests/

# Set a per-test memory limit (fail if exceeded)
pytest --memray --memray-bin-path=./profiles tests/

# Use the marker in tests
# @pytest.mark.limit_memory("100 MB")
# def test_data_processing():
#     process_large_dataset()

# @pytest.mark.limit_leaks("1 MB")
# def test_no_leaks():
#     do_something()

# pytest markers for memory limits
import pytest

# Fail test if it uses more than 100 MB
@pytest.mark.limit_memory("100 MB")
def test_memory_usage():
    data = load_large_dataset()
    result = process(data)
    assert result is not None

# Fail test if it leaks more than 512 KB
@pytest.mark.limit_leaks("512 KB")
def test_no_memory_leaks():
    conn = create_connection()
    conn.execute("SELECT 1")
    conn.close()

Analisando a Saída

Lendo Gráficos de Chama

# Memory flame graph interpretation:
# - X-axis width = proportion of total memory allocated
# - Y-axis depth = call stack (bottom = entry, top = allocation site)
# - Wider boxes = more memory allocated through that code path
# - Click to zoom, search to highlight specific functions
# - Colors distinguish Python frames from native frames

Padrões Comuns

# Find what allocates the most memory
memray flamegraph my_profile.bin
# Look for the widest boxes at the top of the flame graph

# Find temporary allocations (allocation churn)
memray flamegraph --temporary-allocations my_profile.bin
# Temporary allocations cause GC pressure

# Find memory leaks
memray flamegraph --leaks my_profile.bin
# Leaked allocations are never freed during the profiling run

# Compare peak memory vs. final memory
memray stats my_profile.bin
# Large difference between peak and final suggests temporary spikes

Uso Avançado

# Profile with aggregate mode (lower overhead, less detail)
memray run --aggregate my_script.py

# Combine with other profilers
# 1. Use memray for memory, py-spy for CPU
memray run -o mem.bin my_script.py &
py-spy record -o cpu.svg --pid $!

# Profile a Jupyter notebook
# In a notebook cell:
# %load_ext memray
# %memray_flamegraph
# result = expensive_function()

# Transform binary output to different formats
memray flamegraph profile.bin -o flame.html
memray table profile.bin -o table.html
memray tree profile.bin > tree.txt
memray stats profile.bin > stats.txt

Solução de Problemas

# "Error: only Linux is supported" — Memray is Linux-only
# Use Docker on macOS/Windows:
# docker run -it --rm -v $(pwd):/app python:3.11 bash
# pip install memray && memray run /app/my_script.py

# Missing native frames — compile extensions with debug info
CFLAGS="-g" pip install numpy

# Large output files — use aggregate mode
memray run --aggregate -o compact.bin my_script.py

# Profile hangs — ensure no stdin reading in profiled script
memray run --force my_script.py < /dev/null

Referência Rápida

Command	Purpose
`memray run`	Record memory allocations
`memray flamegraph`	Generate interactive HTML flame graph
`memray table`	Generate HTML allocation table
`memray tree`	Show allocation call tree
`memray summary`	High-level allocation summary
`memray stats`	Detailed allocation statistics
`memray run --live`	Real-time TUI tracking
`memray run --native`	Include C/C++ allocations
`--leaks`	Filter to leaked allocations only
`--temporary-allocations`	Show freed allocations