0
# Memray
1

2
A high-performance memory profiler for Python applications that provides comprehensive tracking of memory allocations in Python code, native extension modules, and the Python interpreter itself. Memray features blazing fast profiling with minimal performance impact, native C/C++ call stack tracking, multiple report generation formats, and live monitoring capabilities.
3

4
## Package Information
5

6
- **Package Name**: memray
7
- **Language**: Python
8
- **Installation**: `pip install memray`
9

10
## Core Imports
11

12
```python
13
import memray
14
```
15

16
For specific components:
17

18
```python
19
from memray import Tracker, FileReader, AllocationRecord, TemporalAllocationRecord
20
from memray import compute_statistics, size_fmt, get_symbolic_support
21
from memray import MemrayError, MemrayCommandError
22
```
23

24
## Basic Usage
25

26
```python
27
import memray
28

29
# Profile a Python script
30
with memray.Tracker("profile.bin"):
31
    # Your code to profile
32
    data = [i ** 2 for i in range(100000)]
33
    result = sum(data)
34

35
# Analyze the results
36
with memray.FileReader("profile.bin") as reader:
37
    for record in reader.get_allocation_records():
38
        print(f"Address: {record.address}, Size: {record.size}")
39
```
40

41
Command-line profiling:
42

43
```bash
44
# Profile a script
45
memray run --output profile.bin script.py
46

47
# Generate flame graph report
48
memray flamegraph profile.bin
49
```
50

51
## Architecture
52

53
Memray's architecture consists of three main layers:
54

55
- **Tracking Layer**: High-performance C/C++ tracking hooks that intercept memory allocations with minimal overhead
56
- **Storage Layer**: Efficient binary format for storing allocation records with optional compression
57
- **Analysis Layer**: Python API for reading and analyzing captured data, plus CLI tools for report generation
58

59
The system supports both offline analysis of captured data and live monitoring of running processes, with native stack trace resolution for comprehensive profiling including C extensions.
60

61
## Capabilities
62

63
### Memory Tracking
64

65
Core functionality for tracking memory allocations in Python applications. The Tracker context manager provides the primary interface for capturing allocation data.
66

67
```python { .api }
68
class Tracker:
69
    def __init__(
70
        self, 
71
        file_name=None, 
72
        *, 
73
        destination=None, 
74
        native_traces=False,
75
        memory_interval_ms=10, 
76
        follow_fork=False, 
77
        trace_python_allocators=False,
78
        file_format=FileFormat.ALL_ALLOCATIONS
79
    ): ...
80
```
81

82
[Memory Tracking](./memory-tracking.md)
83

84
### File I/O and Data Analysis
85

86
Reading and analyzing captured memory profiling data. Includes file and socket readers for both offline analysis and live monitoring.
87

88
```python { .api }
89
class FileReader:
90
    def __init__(self, file_name, *, report_progress=False, max_memory_records=10000): ...
91
    def get_allocation_records(self): ...
92
    def get_high_watermark_allocation_records(self, merge_threads=True): ...
93
    def get_leaked_allocation_records(self, merge_threads=True): ...
94

95
class SocketReader:
96
    def __init__(self, port: int): ...
97
    def get_current_snapshot(self, *, merge_threads: bool): ...
98
```
99

100
[File I/O and Data Analysis](./file-io.md)
101

102
### CLI Commands
103

104
Command-line interface for profiling applications and generating reports. Provides tools for capturing profiles, generating visualizations, and analyzing memory usage patterns.
105

106
```bash
107
memray run [options] script.py
108
memray flamegraph [options] capture_file.bin
109
memray table [options] capture_file.bin
110
memray live [options] port
111
```
112

113
[CLI Commands](./cli-commands.md)
114

115
### IPython Integration
116

117
Enhanced integration with IPython and Jupyter notebooks for interactive memory profiling workflows.
118

119
```python { .api }
120
def load_ipython_extension(ipython): ...
121
```
122

123
[IPython Integration](./ipython-integration.md)
124

125
## Types and Data Structures
126

127
```python
128
from typing import List, Tuple, Union
129
from pathlib import Path
130
from datetime import datetime
131
```
132

133
```python { .api }
134
class AllocationRecord:
135
    tid: int
136
    address: int
137
    size: int
138
    @property
139
    def allocator(self) -> int  # Returns AllocatorType enum value
140
    stack_id: int
141
    n_allocations: int
142
    native_stack_id: int
143
    native_segment_generation: int
144
    thread_name: str
145

146
    def stack_trace(self, max_stacks=None): ...
147
    def native_stack_trace(self, max_stacks=None): ...
148
    def hybrid_stack_trace(self, max_stacks=None): ...
149

150
class MemorySnapshot:
151
    time: int
152
    rss: int
153
    heap: int
154

155
class Metadata:
156
    start_time: datetime
157
    end_time: datetime
158
    total_allocations: int
159
    total_frames: int
160
    peak_memory: int
161
    command_line: str
162
    pid: int
163
    main_thread_id: int
164
    python_allocator: str
165
    has_native_traces: bool
166
    trace_python_allocators: bool
167
    file_format: FileFormat
168

169
class AllocatorType:
170
    MALLOC = 1
171
    FREE = 2
172
    CALLOC = 3
173
    REALLOC = 4
174
    POSIX_MEMALIGN = 5
175
    ALIGNED_ALLOC = 6
176
    MEMALIGN = 7
177
    VALLOC = 8
178
    PVALLOC = 9
179
    MMAP = 10
180
    MUNMAP = 11
181
    PYMALLOC_MALLOC = 12
182
    PYMALLOC_CALLOC = 13
183
    PYMALLOC_REALLOC = 14
184
    PYMALLOC_FREE = 15
185

186
class FileFormat:
187
    ALL_ALLOCATIONS = 1
188
    AGGREGATED_ALLOCATIONS = 2
189

190
class Destination:
191
    pass
192

193
class FileDestination:
194
    path: Union[pathlib.Path, str]
195
    overwrite: bool = False
196
    compress_on_exit: bool = True
197

198
class SocketDestination:
199
    server_port: int
200
    address: str = "127.0.0.1"
201

202
class TemporalAllocationRecord:
203
    tid: int
204
    address: int
205
    size: int
206
    @property
207
    def allocator(self) -> int  # Returns AllocatorType enum value
208
    stack_id: int
209
    n_allocations: int
210
    native_stack_id: int
211
    native_segment_generation: int
212
    thread_name: str
213
    intervals: List[Interval]
214

215
    def stack_trace(self, max_stacks=None): ...
216
    def native_stack_trace(self, max_stacks=None): ...
217
    def hybrid_stack_trace(self, max_stacks=None): ...
218

219
class Interval:
220
    allocated_before_snapshot: bool
221
    deallocated_before_snapshot: bool
222
    n_allocations: int
223
    n_bytes: int
224

225
class MemrayError(Exception):
226
    pass
227

228
class MemrayCommandError(MemrayError):
229
    exit_code: int
230

231
class PymallocDomain:
232
    PYMALLOC_RAW = 1
233
    PYMALLOC_MEM = 2
234
    PYMALLOC_OBJECT = 3
235

236
class SymbolicSupport:
237
    NONE = 1
238
    FUNCTION_NAME_ONLY = 2
239
    TOTAL = 3
240

241
# Type aliases for stack trace elements  
242
PythonStackElement = Tuple[str, str, int]  # (filename, function_name, line_number)
243
NativeStackElement = Tuple[str, str, int]  # (filename, function_name, line_number)
244

245
# Constants
246
RTLD_NOW: int
247
RTLD_DEFAULT: int
248
```