A delightful CLI tool for analyzing .NET memory dumps (.gcdump files). Provides heap analysis, type statistics, retained size calculations, object inspection, and memory leak detection with both command-line and interactive modes.
$ dotnet add package dotnet-dumplingA 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.
dotnet tool install -g dotnet-dumpling
Analyze a heap dump and display the top 20 types by retained size:
dumpling analyze heap.gcdump
Show more or fewer types:
dumpling analyze heap.gcdump --top-types 50
Export results as JSON for further processing:
dumpling analyze heap.gcdump --format json > analysis.json
Export as CSV for Excel analysis:
dumpling analyze heap.gcdump --format csv > analysis.csv
Launch the interactive terminal UI to explore the heap:
dumpling analyze heap.gcdump --interactive
In interactive mode, you can:
Compare multiple heap dumps to identify memory growth and changes:
dumpling compare before.gcdump after.gcdump
Show only types with significant growth:
dumpling compare before.gcdump after.gcdump --threshold 0.05 # 5% minimum change
Interactive comparison exploration:
dumpling compare before.gcdump after.gcdump --interactive
analyzeMain 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)compareCompare 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 TotalSizeDeltaUse 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>
┌─────────────────────────┬────────┬──────────────┬────────────────┬──────────┐
│ 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% │
└─────────────────────────┴────────┴──────────────┴────────────────┴──────────┘
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 50
Types 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.json
For 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 --interactive
Focus 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
Apache License 2.0 - see LICENSE file for details.
Dumpling's heap analysis algorithms are inspired by the excellent work in:
Because we're analyzing dump files, and dumplings are delightful! 🥟