Mem Leak Inspector

Mem Leak Inspector is a server-side diagnostics mod that tracks live object instances, snapshots heap state, diffs changes over time, highlights leaking chunks in-world, and exports everything to CSV, JSON, or an offline browser dashboard.

It started as a simple "count the entities and tell me if the number keeps going up" tool for tracking down a stubborn memory leak on a modded server. That worked, so I added diffing between snapshots, then heatmaps, then thread monitoring, and by 1.1 the single-file architecture was holding things together with duct tape. Version 2.0 is a ground-up rewrite - same commands, same features, cleaner internals, and a proper test suite so things don't regress when I add the next thing.

Server-side only. No client install required. Vintage Story 1.22+.

---

What it does

The core workflow is: take a snapshot, do something, take another snapshot, diff them. The diff tells you which types grew and by how much. From there you can drill down:

• Memory snapshots - capture live instance counts per type, estimated memory footprint, per-chunk density, and optional per-instance positions. Snapshots save to compressed JSON with configurable retention.
• Snapshot diffing - compare any two snapshots to see which types grew, shrank, or appeared. /mem diff before after is the command you'll use most.
• In-world heat overlay - /mem showheat sends chunk-level colored highlights to all online players showing where instance growth is concentrated. Red means something's accumulating there.
• Type watchers - /mem watch EntityItem 30 polls that type every 30 seconds and logs whether the count is stable, growing, or "LEAKING". /mem alertwatch does the same thing across all types with configurable spike thresholds.
• Thread monitoring - see every OS-level thread's state, wait reason, and CPU time. The background logger builds a rolling history and exports ASCII graphs and CSV on stop.
• .NET runtime counters - live sampling of allocation rate, GC heap size, working set, and collection counts. Export the full history as a wide CSV for charting in Excel or a notebook.
• Tracking filters - regex-based allow/deny lists so you only track what matters. Exclude particle systems and transient effects that would otherwise dominate the counts.
• Teleport to instance - /mem tp <id> jumps you to the world position of any tracked entity or block entity. Useful when you know what is leaking and need to see where.

Everything exports to CSV or JSON. The included offline dashboard (a static HTML page) lets you drag-and-drop exported files for sorting, filtering, and charting without any server connection.

---

Who it's for

Server admins tracking down why memory usage climbs over a play session. Take periodic snapshots, diff them, and the growing types point you toward the problem - usually a mod spawning entities that never despawn, or block entities accumulating in chunks that should have been unloaded.

Mod developers profiling their own code. Watch a specific type while you test a feature, and the log tells you immediately if instances are leaking. The per-instance position tracking and teleport command let you inspect exactly where the leaked objects ended up.

Anyone debugging performance. The thread monitor and runtime counters catch problems that aren't visible in the entity count - threads stuck in unexpected states, GC pressure from allocation-heavy code paths, working-set growth that doesn't correlate with entity counts.

---

Quick start

<table style="border-collapse: collapse; margin: 8px auto;"> <tbody> <tr> <td style="padding: 4px 24px 4px 0;">/mem snap before</td> <td>Take a baseline snapshot</td> </tr> <tr> <td style="padding: 4px 24px 4px 0;">(do the thing you suspect leaks)</td> <td>&nbsp;</td> </tr> <tr> <td style="padding: 4px 24px 4px 0;">/mem snap after</td> <td>Take a second snapshot</td> </tr> <tr> <td style="padding: 4px 24px 4px 0;">/mem diff before after</td> <td>See what changed</td> </tr> <tr> <td style="padding: 4px 24px 4px 0;">/mem showheat</td> <td>Highlight growth in-world</td> </tr> </tbody> </table>

All commands require the controlserver privilege. Use /help mem for the full list.

---

Configuration