DumpDetective.Cli 3.4.0

🔍 DumpDetective

Your production service just fell over. You have a .dmp file and no idea where to start.

DumpDetective turns that dump into an interactive HTML report in one command — health score, prioritized findings, and 30 targeted sub-reports covering memory leaks, thread deadlocks, async backlogs, GC pressure, event handler leaks, and more. All run in parallel from a single heap walk.

Works with .nettrace and .etl trace files too: 29 trace sub-reports covering CPU hot paths, allocations, GC pauses, contention, HTTP, SQL, ThreadPool starvation, and more.

No steep learning curve. No manual .windbg commands. No hours debugging. Just answers.

⚡ Quick Start

Step 1: Install (one time)

dotnet tool install --global DumpDetective.Cli

Step 2: Analyze (5–30 seconds)

DumpDetective analyze app.dmp --full
# Creates app.html with health score, findings, and 30 sub-reports

Step 3: Investigate

• Open app.html in your browser
• Review the health score (0–100) and findings
• Explore interactive charts, sortable tables, and detailed call stacks
• Dark mode toggle available

Maintenance

dotnet tool update --global DumpDetective.Cli    # update to latest
dotnet tool uninstall --global DumpDetective.Cli # remove

🎯 Five Minutes to an Answer

# 1. Full scored report — 30 sub-reports in parallel
DumpDetective analyze app.dmp --full

# 2. Save for replay (no need to keep the dump file open later)
DumpDetective analyze app.dmp --full --output report.bin
DumpDetective render report.bin --output report.html

# 3. Pre-build caches once so every future run completes in seconds
DumpDetective load app.dmp

# 4. Trace file instead of a dump
DumpDetective trace-analyze app.nettrace

# 5. Both — cross-source correlation links trace signals to heap evidence
DumpDetective trace-dump-analyze app.nettrace app.dmp --output incident.html

The HTML report is self-contained: sticky sidebar navigation, collapsible sections, sortable/filterable tables, embedded charts, and a dark mode toggle. Share it as a single file.

🏆 What You Get

💾 Memory Dump Commands

All commands work with .dmp, .mdmp (WinDbg), and .core (Linux) files. Commands run in seconds on cached dumps.

⏱️ Trace Commands

All commands work with .nettrace and .etl trace files. Analyze one trace or correlate multiple traces with a heap dump.

📄 Output Formats

Every command writes <dump-name>.html by default. Use -o / --output or --format to change it. Both flags are repeatable:

DumpDetective heap-stats app.dmp -o report.html -o report.bin  # both at once
DumpDetective analyze app.dmp --full --format bin               # auto-named .bin

🔌 Plugins & Custom Commands

Extend DumpDetective with your own analysis logic — no source code changes needed.

Drop a .NET class library anywhere in plugins/ (next to the exe) or ~/.dumpdetective/plugins/ and DumpDetective loads it automatically. Your commands appear in --help, run standalone, and can participate in analyze --full.

public sealed class TopStringsCommand : ICommand
{
    public string Name    => "top-strings";
    public string Description => "Top 20 strings by instance count.";
    public bool   IncludeInFullAnalyze => true;
    public string Category => "My Custom Commands";

    public int Run(string[] args)
    {
        var a = CliArgs.Parse(args);
        return CommandBase.Execute(a, Render);
    }

    public void Render(DumpContext ctx, IRenderSink sink)
    {
        CommandBase.RenderHeader("Top Strings", ctx, sink);
        var top = ctx.Heap.EnumerateObjects()
            .Where(o => o.Type?.Name == "System.String")
            .OrderByDescending(o => o.Size)
            .Take(20);
        sink.Table(["Address", "Size", "Value"],
            top.Select(o => new[] { o.Address.ToString("x"), o.Size.ToString(),
                                    o.AsString() ?? "" }).ToList());
    }
}

# Compile as a class library targeting net8.0 (or net10.0), then:
cp MyPlugin.dll plugins/
DumpDetective top-strings app.dmp
DumpDetective analyze app.dmp --full --with-plugins  # include in full-analyze

See Docs/Plugins.md for the full API: heap-walk contribution, cache pinning, trace sub-analyzers, and cross-source correlation rules.

🛠️ Requirements

⚙️ Advanced Usage & Tips

Performance optimization

# Pre-build indexes once so all future runs are instant
DumpDetective load app.dmp

# Subsequent runs will reuse .bfs.idx and .idom.idx caches
DumpDetective heap-stats app.dmp             # runs in <1 second
DumpDetective dominator-tree app.dmp         # instant retained-size queries

Save & replay reports (no dump file needed later)

# During incident, build and save report
DumpDetective analyze app.dmp --full --output incident.bin

# Later, convert to HTML or compare with another report
DumpDetective render incident.bin --output incident.html
DumpDetective diff incident.bin baseline.bin --output changes.html

Multi-format output

# Generate multiple formats in one command
DumpDetective analyze app.dmp --full \
  --output report.html \
  --output report.json \
  --output report.md

# Or use --format for auto-naming
DumpDetective analyze app.dmp --full --format html --format json

Configure analysis thresholds

Place dd-thresholds.json in your working directory to customize health score rules:

{
  "CriticalThresholds": {
    "HeapWaste": 0.25,
    "DeadObjectsRatio": 0.10
  },
  "WarningThresholds": {
    "HeapWaste": 0.15,
    "DeadObjectsRatio": 0.05
  }
}

❓ Quick Reference

When to use what?

Common workflows

# Incident investigation
DumpDetective analyze app.dmp --full                      # Get overview + findings
DumpDetective dominator-tree app.dmp -o dominator.html   # Dig into top retained paths
DumpDetective trace-dump-analyze app.nettrace app.dmp    # Cross-source root cause

# Performance tuning
DumpDetective alloc-trace app.nettrace -o alloc.html     # Hot allocation call stacks
DumpDetective gc-trace app.nettrace -o gc.html           # GC pause analysis
DumpDetective heap-fragmentation app.dmp                 # Large-object heap waste

# Trend analysis
DumpDetective load app-before.dmp app-after.dmp          # Pre-build caches
DumpDetective trend-analysis app-before.dmp app-after.dmp

❓ FAQ & Troubleshooting

Q: How long does analysis take?
A: First run builds indexes (~5–30s for small dumps, ~2–5 min for 15GB+ dumps). Subsequent runs are instant (<1s) because caches are reused.

Q: What's the health score?
A: A 0–100 score reflecting heap health. Deducted for leaks, fragmentation, deadlocks, etc. Configurable via dd-thresholds.json.

Q: Can I use DumpDetective on Linux?
A: Yes, for .core dumps (supported since v3.3.0). For WinDbg .dmp/.mdmp files, you need Windows.

Q: How much memory does DumpDetective need?
A: Roughly 1–2x the dump size. A 15 GB dump needs ~20 GB RAM. Use DumpDetective load to pre-build caches if you're tight on resources.

Q: Can I add my own analysis commands?
A: Yes! Drop a .NET plugin in plugins/ or ~/.dumpdetective/plugins/. See Docs/Plugins.md.

Q: What cache files can I delete?
A: .bfs.idx, .idom.idx, and .ddcache/ are safe to delete — they rebuild automatically. Keep the .dmp file.

Q: Is my dump file kept secure?
A: Dumps are processed locally only. No data is sent anywhere. Analyze offline dumps confidently.

Q: Why is the HTML report so large?
A: It's fully self-contained (all CSS, JS, data embedded). One file = one complete, shareable report.

📚 Full Documentation

• Docs/documentation.md — complete command reference, options, performance benchmarks, health score thresholds
• Memory Analysis Guide — deep-dive on dump commands with examples
• Trace Analysis Guide — deep-dive on trace commands with examples
• Cache Inventory — understanding .bfs.idx, .idom.idx, .ddcache lifecycle and performance
• Plugin System — write and install custom commands with full API reference
• Architecture — project structure, dependency graph, design decisions

📝 License

MIT