187 lines
4.4 KiB
Markdown
187 lines
4.4 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
dotnet run --project tools/DtpSnapshotExtractor -- snapshots/js-ordered-consume.dtp
|
||
```
|
||
|
||
Expected: JSON is emitted successfully.
|
||
|
||
**Step 3: Commit**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
|
||
```
|
||
|
||
Expected: JSON is emitted successfully.
|
||
|
||
**Step 3: Commit**
|
||
|
||
```bash
|
||
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**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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**
|
||
|
||
```bash
|
||
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"
|
||
```
|