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.

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:

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