trace-operations

name	trace-operations
description	Capture and replay 3Lens traces for debugging, performance analysis, and regression testing. Use when recording traces, opening/replaying saved traces, or exporting trace data for sharing. Use when this capability is needed.
metadata	{"author":"adriandarian"}

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

1. Before refactoring: "Record a baseline trace before the shader refactor"
2. Bug reproduction: "Capture a trace when the memory spike occurs"
3. 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.