tomevault-io Trace Operations
Trace operations are the foundation of 3Lens analysis. Use these commands to capture, replay, and export render traces.
When to Use
- Recording a baseline before making changes
- Capturing a performance spike reproduction
- Sharing traces for debugging or collaboration
- Comparing before/after states
Commands
Record a Trace
# Record for a specific duration
3lens trace:record --duration 10s --out ./traces/runA.json
# Record a specific number of frames
3lens trace:record --frames 300 --out ./traces/runA.json
# Record until frame time stabilizes
3lens trace:record --until-idle --out ./traces/runA.json
Options:
| Option | Description |
|---|---|
--duration <seconds> |
Record for specified time |
--frames <count> |
Record specified number of frames |
--until-idle |
Record until frame time stabilizes |
--mode <MINIMAL|STANDARD|DEEP> |
Capture mode |
--contexts <ids> |
Specific contexts to record |
Open/Replay a Trace
# Open in trace viewer UI
3lens trace:open ./traces/runA.json
# Open for headless analysis
3lens trace:open ./traces/runA.json --headless
Export Trace
# Export with minimal profile
3lens trace:export ./traces/runA.json --profile MINIMAL --out ./report.json
# Export with full redacted profile (safe for sharing)
3lens trace:export ./traces/runA.json --profile FULL_REDACTED --out ./share.json
Export Profiles: MINIMAL, STANDARD, FULL, FULL_REDACTED
Agent Use Cases
- Before refactoring: "Record a baseline trace before the shader refactor"
- Bug reproduction: "Capture a trace when the memory spike occurs"
- CI regression: "Record traces for baseline comparison"
Additional Resources
- For detailed command syntax, see .cursor/commands/
- For trace format details, see .cursor/contracts/capture.md
- Commands: trace-record, trace-open
- Skill: diff-operations
- Skill: query-operations
- Agent: trace-analyzer
- Contract: storage.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.