memlog

A lightweight and colorful Python memory allocation tracking tool built on top of tracemalloc.

memlog helps you monitor memory usage, identify potential memory leaks, and compare memory snapshots during function execution or within a specific context. It provides clear, formatted table output in your terminal.

English | 中文

Features

• Stop/Clear Support: Support for stopping and clearing traces.
• Environment-controlled activation: Enable tracking only when needed using an environment variable.
• Synchronous & Asynchronous Support: Works seamlessly with both standard and async functions.
• Flexible Usage: Use as a decorator, context manager, or manual API.
• Filtering Capabilities: Include specific file paths or modules using filters (supports string list or tracemalloc.Filter).
• Colorful Output: Displays memory statistics and differences in a clean, readable table format (automatically detects TTY for color).
• Comparison Modes: Compare current memory against a baseline (first snapshot) or the start of a specific block.

Installation

pip install memlog

Usage

1. Using as a Decorator

Easily track memory usage of a specific function.

import memlog

# Start tracking
memlog.start()

@memlog.snapshot(title="Data Processing", top_k=5)
def process_data():
    # Your memory-intensive code here
    data = [i for i in range(1000000)]
    return len(data)

# When called, it will print a comparison table showing memory changes
process_data()

The decorator also supports async functions:

@memlog.snapshot(title="Async Task")
async def run_task():
    await asyncio.sleep(1)

2. Using as a Context Manager

Track memory within a specific block of code.

import memlog

# Start tracking
memlog.start()

with memlog.snapshot_manager(title="Block Comparison", top_k=3):
    temp_list = [str(i) for i in range(50000)]
    # Comparison table is printed when exiting the block

3. Manual Snapshotting

For more granular control, use the manual API.

import memlog

# Start tracking (automatically called if MEMLOG_ENABLE=1)
memlog.start()

# Take an initial snapshot
s1 = memlog.take_snapshot("Initial State")

# ... run some code ...

# Take another snapshot and compare
s2 = memlog.take_snapshot("After Operation")
s2.compare_to(s1).show(top_k=10)

API Reference

Core Functions

• memlog.start(): Initializes tracemalloc and records the "First Snapshot".
• memlog.stop(): Stops tracemalloc and clears snapshots.
• memlog.clear(): Clears tracemalloc traces and snapshots.
• memlog.take_snapshot(title=None, filters=None): Captures the current memory state.
  • filters: A list of strings or tracemalloc.Filter objects to include in the traceback (e.g., ["src/memlog"]).
• memlog.get_first_snapshot(): Returns the very first snapshot taken when memlog was started.
• memlog.snapshot(mode='start', title=None, filters=None, top_k=10, key_type=KeyType.TRACEBACK): A decorator for functions.
  • mode='start': Compares the end state to the state just before the function started.
  • mode='first': Compares the end state to the global "First Snapshot".
• memlog.snapshot_manager(mode='start', title=None, filters=None, top_k=10, key_type=KeyType.TRACEBACK): A context manager.

Snapshot Methods

• snapshot.compare_to(other_snapshot, key_type=KeyType.TRACEBACK, cumulative=False): Returns a comparison object between two snapshots.
• snapshot.compare(key_type=KeyType.TRACEBACK, cumulative=False): Compares current snapshot to the global "First Snapshot".
• snapshot.statistics(key_type=KeyType.TRACEBACK, cumulative=False): Returns statistics for the snapshot.
• snapshot.dump(filename): Save snapshot to a file.
• snapshot.load(filename): Load snapshot from a file.

Statistics Methods

• statistics.show(top_k=10): Prints the formatted statistics to stdout.
• statistics.show_table(top_k=10): Prints a formatted table to stdout.

License

This project is licensed under the MIT License - see the LICENSE file for details.