How bloomberg/memray works
Project Overview
• Type & Purpose: Memray is a memory profiling tool for Python. Its primary function is to track memory allocations – including those in Python code and native C/C++ extensions – and generate various types of reports (flame graphs, tables, live views, etc.) to help analyze and diagnose memory usage and potential leaks.
• Operational Modes: It works as a CLI tool, can be used programmatically via its API, and also supports live terminal interactions and integration with pytest.
Major Components & Architecture
a. CLI Interface and Command Routing:
• This component handles user input and dispatches commands such as “run”, “flamegraph”, “table”, “tree”, “live”, “parse”, “summary”, and “stats”.
• Files/Directories Involved: The “src/memray/commands” directory defines the various subcommands (e.g., attach.py, flamegraph.py, run.py) realized in the CLI.
b. Memory Tracking Engine:
• Core Memory Profiling: The engine is responsible for tracking memory usage at the Python level. It sets up hooks to capture call stacks, allocates memory records, and aggregates tracking details.
• Native Integration: Through native extensions implemented in C/C++ (e.g., in “src/memray/_memray” where you see .pyx, .pxd files along with C/C++ source files such as hooks.cpp, snapshot.cpp), Memray enhances Python’s tracking with low-level memory allocation insights.
• API Usage: The tracker is exposed as a context manager (e.g., memray.Tracker) that developers can use inside Python scripts.
c. Report Generation / Reporter Subsystem:
• Reporters Process Data: This component transforms the binary output (result files saved by “memray run”) into reports. Reporters include HTML generators (flamegraph, table), terminal-based views, and TUI-based live dashboards.
• Files/Directories Involved: “src/memray/reporters” contains modules and templates for formatting output (for example, flamegraph.py and table.py alongside the corresponding assets and templates).
d. Build, Configuration, and Testing Infrastructure:
• Build System and Extensions: Configuration files like Dockerfile, Makefile, pyproject.toml, and CMakeLists (inside _memray) indicate how native extensions are built and integrated.
• Testing and Benchmarking: The “tests” directory (with both unit and integration tests) and “benchmarks” directory provide tests and performance measurements, ensuring correct tracking and report generation.
• Documentation: The “docs” directory and associated files offer guidance and detailed usage instructions.
Relationships & Data Flow
• User Interaction: The user interacts with Memray via command line or by integrating its API in the application.
• Execution Flow: Running a command (e.g., “memray run my_script.py”) triggers the memory tracker, which monitors Python and native allocations. The tracker logs data into a binary file.
• Report Processing: The corresponding reporter (e.g., “memray flamegraph”) then reads the binary file, applies the transformation (using the reporter templates, styles, and libraries) to generate the flame graph or table view.
• Live Mode Flow: In live mode, a TUI periodically refreshes with aggregated memory statistics – transitioning seamlessly between threads and sorting metrics as needed.
Architectural Patterns & Design Principles
• Modular Design: The separation between the CLI layer, memory tracking engine, and reporter subsystem exemplifies “separation of concerns.”
• Extensions & Native Integration: The clear boundary between Python logic and native/C++ code (encapsulated in _memray) shows how performance-critical functionality is isolated.
• Configurability & Extensibility: With support for plugins (e.g., pytest integration via pytest-memray) and user-collected reports, the design promotes extensibility.
Technologies & Tools Referenced
• Language/Frameworks: Python (with Cython for native extensions), C/C++, and usage of build tools like Make, Docker, and CMake.
• CI/CD & Testing: GitHub Actions workflows, pre-commit hooks, and various test suites.
• Visualization Libraries & Front-End: HTML, CSS, and JavaScript assets for generating flame graphs and table reports.