libmallocvis ― A One-Click Memory Analysis Tool for the Lazy

[中文文档] | English | Chinese

libmallocvis.so is a visualization tool that shows heap allocations made via the libc malloc/realloc/calloc/free calls, for programs written in Rust, C++, and more. It uses a multithreaded interception library with a separate server process to achieve fine-grained tracing and analysis, while imposing minimal overhead on the target application.

With this tool, you can capture flame-graph snapshots at any time or thread to pinpoint heap usage in detail. Best of all, libmallocvis ships as a single self-contained binary with a built-in WebAssembly frontend panel. You can extract the tracer library into any directory in one step, and on server startup it prints a ready-to-copy command so you don’t have to fiddle with environment variables or config files to start real-time analysis.

Clear & Intuitive Flame-Graph Dashboard

📋 Quick Start

# 1. Extract the interception library into the current dir
❯ mallocvis --extract-tracer

# 2. Start the server (in background)
❯ mallocvis &

# 3. View results in browser
Visit → http://localhost:8080

# 4. Run your program under interception
❯ LD_PRELOAD=./libmallocvis.so <your_program>

✨ Core Features

• Dashboard & Stats Overview Live display of total allocations, call counts, hotspot functions, and other key metrics.

• Heap Growth Trends & Alloc/Free Comparison Compare allocation vs. free volumes over time to spot abnormal memory growth.

• Time-Series Memory Usage & Leak Detection Visualize memory usage over time with automatic suspected-leak markers.

• Advanced Analysis Panel Deep dives by thread, function, call stack, and more.

• Detailed Error Reports Capture and display full context when interception or generation fails.

• Multi-Process Support Simultaneously monitor and analyze multiple processes.

📚 Documentation

• Principles — Analysis of memory interception and flame-graph generation
• Development — Build, development, and contribution guide
• Usage — Detailed usage instructions and best practices

🏗️ Architecture

libmallocvis follows a modular architecture comprising:

• Interceptor Library libmallocvis.so: Captures, packages, and emits memory events
• Analysis Server mallocvis_server: Asynchronous multithreaded processing and flame-graph creation
• Frontend UI mallocvis_ui: WebAssembly-based single-page app for interactive visualization

The final mallocvis executable bundles all three:

1. mallocvis --extract-tracer extracts the interceptor library
2. mallocvis starts the server directly
3. Open http://localhost:8080 to begin real-time analysis

🛠️ Install · Run · Test

Download Release

• Download here

Build from Source (Release Mode)

❯ git clone https://github.com/zmr-233/libmallocvis.git
❯ cd libmallocvis
❯ make server-release    # Build release binary
# Binary is at: target/release/mallocvis

Test Run (Debug Mode)

❯ make run           # Start server
❯ make test-select  # Generate sample data under tests/
# Then visit: http://localhost:8080

📖 Detailed Steps

1. Extract the Library

   ❯ cd <your_target_dir>
   ❯ mallocvis --extract-tracer
   # Creates libmallocvis.so in the current dir

2. Start the Server Supports default and custom options:

   # Default launch
   ❯ mallocvis &
   
   # Quick customize
   ❯ mallocvis -p 8079 -w 8080 -a 127.0.0.1 &
   
   # Full options
   ❯ mallocvis --data-port 8079 \
               --web-port 8080 \
               --address 127.0.0.1 \
               --cache-dir /tmp/mallocvis_cache &
   # Also prints the one-click run command for your app

3. Run Your App Match server ports; use env vars or a .env file:

   # Default
   ❯ LD_PRELOAD=./libmallocvis.so <your_program>
   
   # Custom
   ❯ LD_PRELOAD=./libmallocvis.so \
       RUST_LOG=debug \
       SERVER_ADDRESS=127.0.0.1:8079 \
       CACHE_DIR=/tmp/mallocvis_cache \
       <your_program>

4. One-Click Run Command After starting the server, you’ll see:

   🔻 Usage: Copy and run this command to trace your application:
   -----------------------------------------------------------
   LD_PRELOAD=./libmallocvis.so \
   SERVER_ADDRESS=127.0.0.1:8079 \
   CACHE_DIR=/tmp/mallocvis_cache \
   <your_program>
   -----------------------------------------------------------
   

🔧 How It Works

libmallocvis leverages the Linux dynamic loader’s LD_PRELOAD mechanism and the RTLD_NEXT API to transparently intercept libc’s malloc/free calls.

See Principles for details.

🤝 Contributing

Contributions are welcome! See Development for guidelines.

📄 License

This project is licensed under MIT. See LICENSE.

🔗 Related Links

• Project Homepage
• Issue Tracker
• Discussions

References

• mallocvis (C++) by Archibate
• glibc malloc internals
• LD_PRELOAD interception in Rust
• Brendan Gregg: Memory Leak Flame Graphs
• FlameGraph GitHub
• The Rust Performance Book — Profiling
• Memray — Flame Graph Reporter

---

⭐ If you find this project helpful, please give it a ⭐ on GitHub!