0
# Memory Tracking
1

2
Core functionality for tracking memory allocations in Python applications. The Tracker provides the primary interface for capturing allocation data with configurable options for different profiling scenarios.
3

4
## Capabilities
5

6
### Tracker Context Manager
7

8
The main interface for memory profiling that captures allocation events during execution. Can output to files or stream to sockets for live monitoring.
9

10
```python { .api }
11
class Tracker:
12
    def __init__(
13
        self, 
14
        file_name=None, 
15
        *, 
16
        destination=None, 
17
        native_traces=False,
18
        memory_interval_ms=10, 
19
        follow_fork=False, 
20
        trace_python_allocators=False,
21
        file_format=FileFormat.ALL_ALLOCATIONS
22
    ):
23
        """
24
        Initialize memory tracker.
25

26
        Parameters:
27
        - file_name: str or pathlib.Path, output file path
28
        - destination: FileDestination or SocketDestination, alternative to file_name
29
        - native_traces: bool, whether to capture native stack frames
30
        - memory_interval_ms: int, interval for RSS updates (default: 10ms)
31
        - follow_fork: bool, continue tracking in forked processes
32
        - trace_python_allocators: bool, whether to trace Python allocators separately
33
        - file_format: FileFormat, output format (ALL_ALLOCATIONS or AGGREGATED_ALLOCATIONS)
34
        """
35

36
    def __enter__(self) -> 'Tracker':
37
        """Activate memory tracking."""
38

39
    def __exit__(self, exc_type, exc_value, exc_traceback):
40
        """Deactivate memory tracking."""
41
```
42

43
Usage examples:
44

45
```python
46
# Basic file tracking
47
with memray.Tracker("profile.bin"):
48
    # Code to profile
49
    data = process_large_dataset()
50

51
# With native traces
52
with memray.Tracker("profile.bin", native_traces=True):
53
    import numpy as np
54
    array = np.zeros((1000, 1000))
55

56
# Using FileDestination with options
57
import memray
58
from memray import FileDestination
59

60
destination = FileDestination(
61
    path="profile.bin",
62
    overwrite=True,
63
    compress_on_exit=True
64
)
65

66
with memray.Tracker(destination=destination):
67
    # Code to profile
68
    pass
69

70
# Live streaming to socket
71
from memray import SocketDestination
72

73
destination = SocketDestination(server_port=12345, address="localhost")
74

75
with memray.Tracker(destination=destination):
76
    # Code being profiled in real-time
77
    process_data()
78
```
79

80
### Thread Tracing
81

82
Automatic thread tracking for multi-threaded applications.
83

84
```python { .api }
85
def start_thread_trace(frame, event, arg):
86
    """
87
    Thread tracing function for automatic thread tracking.
88
    
89
    Parameters:
90
    - frame: frame object
91
    - event: str, tracing event type
92
    - arg: event argument
93
    
94
    Returns:
95
    - start_thread_trace function (itself)
96
    """
97
```
98

99
### Utility Functions
100

101
Debug and configuration functions for memory tracking.
102

103
```python { .api }
104
def dump_all_records(file_name):
105
    """
106
    Debug function to dump all records from a memray file.
107
    
108
    Parameters:
109
    - file_name: str, path to memray capture file
110
    
111
    Returns:
112
    - None
113
    """
114

115
def set_log_level(level: int):
116
    """
117
    Configure log message threshold for memray.
118
    
119
    Parameters:
120
    - level: int, minimum log level (logging.WARNING by default)
121
    
122
    Returns:
123
    - None
124
    """
125
```
126

127
Usage example:
128

129
```python
130
import logging
131
import memray
132

133
# Set debug logging
134
memray.set_log_level(logging.DEBUG)
135

136
# Profile and dump for debugging
137
with memray.Tracker("debug.bin"):
138
    problematic_function()
139

140
# Dump all records for analysis
141
memray.dump_all_records("debug.bin")
142
```
143

144
## Destination Types
145

146
### FileDestination
147

148
Specifies file output for captured allocations with compression and overwrite options.
149

150
```python { .api }
151
class FileDestination:
152
    path: Union[pathlib.Path, str]
153
    overwrite: bool = False
154
    compress_on_exit: bool = True
155
```
156

157
### SocketDestination
158

159
Specifies socket streaming for live monitoring of allocations.
160

161
```python { .api }
162
class SocketDestination:
163
    server_port: int
164
    address: str = "127.0.0.1"
165
```
166

167
### Base Destination
168

169
Abstract base for all destination types.
170

171
```python { .api }
172
class Destination:
173
    pass
174
```