A delightful CLI tool for analyzing .NET memory dumps.
Dumpling is a cross-platform .NET global tool that helps developers analyze heap dumps (.gcdump files) from .NET applications. It provides both quick command-line analysis and an interactive mode for exploring memory usage patterns, finding memory leaks, and understanding object retention.
- Type Analysis: Group objects by type with counts, sizes, and retained memory
- Retained Size Calculations: Understand true memory impact using dominator tree analysis
- Instance Inspection: View sample instances with addresses and individual retained sizes
- Retainer Analysis: Trace reference paths to understand why objects stay in memory
- Multiple Output Formats: Table (default), JSON, or CSV for easy integration
- Interactive Mode: Explore heap data with a rich terminal UI
- Heap Comparison: Compare multiple heap dumps to identify memory growth and changes over time
- Reference Paths: Find GC roots keeping objects alive
- Fast & Efficient: Optimized algorithms for analyzing large heap dumps
dotnet tool install -g dotnet-dumplingAnalyze a heap dump and display the top 20 types by retained size:
dumpling analyze heap.gcdumpShow more or fewer types:
dumpling analyze heap.gcdump --top-types 50Export results as JSON for further processing:
dumpling analyze heap.gcdump --format json > analysis.jsonExport as CSV for Excel analysis:
dumpling analyze heap.gcdump --format csv > analysis.csvLaunch the interactive terminal UI to explore the heap:
dumpling analyze heap.gcdump --interactiveIn interactive mode, you can:
- Navigate through types and instances
- Search and filter objects
- Drill down into retainers
- Export selected data
Compare multiple heap dumps to identify memory growth and changes:
dumpling compare before.gcdump after.gcdumpShow only types with significant growth:
dumpling compare before.gcdump after.gcdump --threshold 0.05 # 5% minimum changeInteractive comparison exploration:
dumpling compare before.gcdump after.gcdump --interactiveMain analysis command for heap dumps.
Options:
--top-types, -t <number>: Number of top types to display (default: 20)--format, -f <format>: Output format: Table, Json, or Csv (default: Table)--interactive, -i: Launch interactive mode--show-instances, -si: Show sample instances for each type--show-retainers, -sr: Show retainer paths for instances (implies --show-instances)--max-instances, -mi <number>: Maximum instances to show per type (default: 3)
Compare multiple heap dump files to identify changes and memory growth.
Options:
--interactive, -i: Launch interactive mode for exploring comparison results--select-files, -sf: Launch interactive file selection when multiple files are found--format, -f <format>: Output format: Table, Json, or Csv (default: Table)--top-types, -t <number>: Number of top changed types to display (default: 20)--threshold, -th <threshold>: Minimum change percentage to display (default: 0.01 = 1%)--show-all, -a: Show all types including unchanged ones--sort-by, -s <field>: Sort by CountDelta, GrowthPercent, RetainedSizeDelta, or TotalSizeDelta
Use dotnet-gcdump tool to capture heap dumps:
# Install dotnet-gcdump
dotnet tool install -g dotnet-gcdump
# List running .NET processes
dotnet-gcdump ps
# Create a heap dump
dotnet-gcdump collect -p <process-id>- Debug → Windows → Diagnostic Tools
- Take Snapshot
- Export as .gcdump file
- Collect → Collect → Heap Snapshot
- Save as .gcdump file
┌─────────────────────────┬────────┬──────────────┬────────────────┬──────────┐
│ Type │ Count │ Total Size │ Retained Size │ % of Heap│
├─────────────────────────┼────────┼──────────────┼────────────────┼──────────┤
│ System.String │ 10,234 │ 2.45 MB │ 15.67 MB │ 23.45% │
│ System.Byte[] │ 1,523 │ 5.12 MB │ 12.34 MB │ 18.47% │
│ MyApp.CustomerData │ 856 │ 1.23 MB │ 8.91 MB │ 13.34% │
└─────────────────────────┴────────┴──────────────┴────────────────┴──────────┘
- Type: The .NET type name
- Count: Number of instances
- Total Size: Direct memory used by all instances
- Retained Size: Total memory that would be freed if all instances were collected
- % of Heap: Percentage of total retained heap size
Retained Size: The amount of memory that would be freed if an object and all objects it exclusively references were garbage collected. This is often more important than the object's own size for understanding memory impact.
Dominator Tree: Used to calculate retained sizes. An object X dominates object Y if every path from the root to Y goes through X.
Look for types with unexpectedly high retained sizes:
dumpling analyze app.gcdump --top-types 50Types with high retained size relative to their expected usage often indicate memory leaks.
See why objects are staying in memory:
# Show instances and their retainer paths
dumpling analyze app.gcdump --show-retainers
# Get detailed JSON output for analysis
dumpling analyze app.gcdump --show-retainers --format json > retention.jsonFor large production dumps, export to JSON for detailed analysis:
dumpling analyze prod.gcdump --format json | jq '.Types[] | select(.RetainedSize > 10000000)'Compare multiple heap dumps to track memory changes over time:
# Basic comparison showing memory growth
dumpling compare before.gcdump after.gcdump
# Focus on significant changes only
dumpling compare dump1.gcdump dump2.gcdump dump3.gcdump --threshold 0.1
# Export comparison results for analysis
dumpling compare before.gcdump after.gcdump --format json > comparison.json
# Interactive exploration of changes
dumpling compare before.gcdump after.gcdump --interactiveFocus on problematic types with instance details:
# Show 5 instances of each top type
dumpling analyze app.gcdump --top-types 10 --show-instances --max-instances 5- .NET 8.0 or later
- Windows, macOS, or Linux
Apache License 2.0 - see LICENSE file for details.
Dumpling's heap analysis algorithms are inspired by the excellent work in:
- PerfView
- dotnet-heapview
- Microsoft.Diagnostics.Tracing.TraceEvent
Because we're analyzing dump files, and dumplings are delightful! 🥟