natsdotnet/docs/plans/2026-03-14-dtp-parser.md

dotTrace DTP Parser Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a Python-first tool that reads a raw dotTrace .dtp snapshot family and emits JSON call-tree and hotspot data for LLM analysis.

Architecture: A small .NET helper uses JetBrains’ local dotTrace assemblies to decode snapshot storage, performance call-tree nodes, payloads, and metadata. A Python wrapper validates input, builds the helper if needed, runs it, and writes the resulting JSON.

Tech Stack: Python 3 standard library, .NET 10 console app, local JetBrains dotTrace assemblies, unittest

---

Task 1: Add the failing end-to-end test

Files:

• Create: tools/tests/test_dtp_parser.py

Step 1: Write the failing test

Write a unittest test that runs:

python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout

and asserts:

• exit code is 0
• stdout is valid JSON
• call_tree.children is non-empty
• hotspots.inclusive is non-empty
• at least one node name is not marked as special

Step 2: Run test to verify it fails

Run: python3 -m unittest tools.tests.test_dtp_parser -v

Expected: FAIL because tools/dtp_parse.py does not exist yet.

Step 3: Commit

git add tools/tests/test_dtp_parser.py
git commit -m "test: add dtp parser end-to-end expectation"

Task 2: Implement the .NET snapshot extractor

Files:

• Create: tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj
• Create: tools/DtpSnapshotExtractor/Program.cs

Step 1: Write the minimal implementation

Implement a console app that:

• accepts snapshot path and optional output path
• opens the snapshot through JetBrains snapshot storage
• constructs performance call-tree and payload readers
• resolves method names via metadata sections
• builds a JSON object with root tree, thread roots, and hotspot lists
• writes JSON to stdout or output file

Step 2: Run helper directly

Run:

dotnet run --project tools/DtpSnapshotExtractor -- snapshots/js-ordered-consume.dtp

Expected: JSON is emitted successfully.

Step 3: Commit

git add tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj tools/DtpSnapshotExtractor/Program.cs
git commit -m "feat: add dottrace snapshot extractor helper"

Task 3: Implement the Python entrypoint

Files:

• Create: tools/dtp_parse.py

Step 1: Write the minimal implementation

Implement a CLI that:

• accepts snapshot path
• supports --out and --stdout
• checks that dotTrace assemblies exist in the local install
• runs dotnet run --project tools/DtpSnapshotExtractor -- <snapshot>
• forwards JSON output

Step 2: Run the wrapper

Run:

python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout

Expected: JSON is emitted successfully.

Step 3: Commit

git add tools/dtp_parse.py
git commit -m "feat: add python dtp parsing entrypoint"

Task 4: Make the test pass and tighten output

Files:

• Modify: tools/DtpSnapshotExtractor/Program.cs
• Modify: tools/dtp_parse.py
• Modify: tools/tests/test_dtp_parser.py

Step 1: Run the failing test

Run: python3 -m unittest tools.tests.test_dtp_parser -v

Expected: FAIL with an output-schema or execution issue.

Step 2: Fix the minimal failing behavior

Adjust:

• special-node labeling
• JSON schema stability
• helper invocation details
• fallback behavior for unresolved metadata

Step 3: Re-run the test

Run: python3 -m unittest tools.tests.test_dtp_parser -v

Expected: PASS

Step 4: Commit

git add tools/DtpSnapshotExtractor/Program.cs tools/dtp_parse.py tools/tests/test_dtp_parser.py
git commit -m "test: verify dtp parser output"

Task 5: Final verification

Files:

• Modify: none unless fixes are required

Step 1: Run end-to-end extraction

Run:

python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --out /tmp/js-ordered-consume-calltree.json

Expected: JSON file is created.

Step 2: Run test suite

Run:

python3 -m unittest tools.tests.test_dtp_parser -v

Expected: PASS

Step 3: Inspect a hotspot sample

Confirm the JSON contains:

• resolved method names
• inclusive and exclusive hotspot lists
• nested thread call trees

Step 4: Commit

git add docs/plans/2026-03-14-dtp-parser-design.md docs/plans/2026-03-14-dtp-parser.md
git commit -m "docs: add dtp parser design and plan"