Initial commit

commands/trace_analysis.md

@@ -0,0 +1,201 @@
+---
+description: Analyze distributed traces and performance issues with Sentry
+category: debugging
+tools: Task, TodoWrite
+model: inherit
+version: 1.0.0
+---
+
+# Trace Analysis
+
+Investigate distributed traces, transaction performance, and slow requests using Sentry.
+
+## Usage
+
+```bash
+/trace-analysis <trace-id-or-query>
+
+Examples:
+  /trace-analysis "a4d1aae7216b47ff8117cf4e09ce9d0a"
+  /trace-analysis "slow API requests to /checkout"
+  /trace-analysis "traces with >5 second response time"
+  /trace-analysis "performance issues in payment service"
+```
+
+## What This Analyzes
+
+### Trace Components
+
+- Transaction spans (API calls, DB queries, external services)
+- Timing breakdown per span
+- Parent-child span relationships
+- Span operations and descriptions
+
+### Performance Metrics
+
+- Total transaction duration
+- Time spent in each service
+- Database query performance
+- External API latency
+- Network overhead
+
+### Bottleneck Identification
+
+- Slowest spans in trace
+- Sequential vs parallel operations
+- N+1 query detection
+- Inefficient operations
+
+## Example Analyses
+
+### Specific Trace Investigation
+
+```bash
+/trace-analysis "Analyze trace abc123def456: where's the bottleneck?"
+```
+
+### Performance Pattern
+
+```bash
+/trace-analysis "Why are checkout API requests slow today?"
+```
+
+### Service Comparison
+
+```bash
+/trace-analysis "Compare performance of payment service vs order service"
+```
+
+### Database Performance
+
+```bash
+/trace-analysis "Find traces with slow database queries in user service"
+```
+
+## Output Format
+
+Analysis includes:
+
+**Trace Overview**:
+
+- Transaction name and operation
+- Total duration
+- Timestamp
+- Environment and release
+
+**Span Breakdown**:
+
+```
+Transaction: POST /api/checkout (2.4s)
+├─ Authentication (45ms)
+├─ Database Query: SELECT users (120ms)
+├─ External API: Payment Gateway (1.8s) ⚠️ SLOW
+├─ Database Query: INSERT orders (230ms)
+└─ Email Service (180ms)
+```
+
+**Performance Insights**:
+
+- Slowest operations
+- Time distribution (pie chart/percentages)
+- Parallel vs sequential execution
+- Optimization opportunities
+
+**Recommendations**:
+
+- Cache frequently accessed data
+- Optimize specific queries
+- Implement async processing
+- Add timeouts for external calls
+
+## Advanced Analysis
+
+### Multi-Trace Patterns
+
+```bash
+/trace-analysis "Find common bottlenecks across all slow checkout traces today"
+```
+
+### Service Dependencies
+
+```bash
+/trace-analysis "Map service call chain for failed transactions"
+```
+
+### Error Correlation
+
+```bash
+/trace-analysis "Traces that resulted in errors: what went wrong before?"
+```
+
+## Integration Opportunities
+
+### With Error Debugging
+
+```bash
+# Enable debugging plugin (if not already)
+/plugin enable catalyst-debugging
+
+# Combine trace and error analysis
+> "Show me the trace for the transaction that caused error ISSUE-456"
+```
+
+### With Code Changes
+
+After identifying bottleneck:
+
+```bash
+/create-plan "Optimize the slow payment gateway call identified in trace analysis"
+```
+
+## Performance Optimization Workflow
+
+### 1. Identify Slow Transactions
+
+```bash
+/trace-analysis "transactions with >2s response time in last hour"
+```
+
+### 2. Analyze Bottlenecks
+
+```bash
+> "Drill into the slowest trace: which span is the problem?"
+```
+
+### 3. Root Cause
+
+```bash
+> "Why is the database query taking 800ms?"
+```
+
+### 4. Implement Fix
+
+```bash
+/create-plan "Add database index for user lookups based on trace analysis"
+```
+
+### 5. Verify Improvement
+
+```bash
+> "After deploy, compare trace durations before and after"
+```
+
+## Tips
+
+1. **Start with aggregates** - "slow checkouts" before diving into specific traces
+2. **Look for patterns** - One slow trace might be an outlier, many indicate systemic issue
+3. **Check external dependencies** - Third-party APIs often cause slowdowns
+4. **Consider concurrency** - Sequential operations that could be parallel
+5. **Database queries** - N+1 queries, missing indexes, inefficient queries
+
+## Context Cost
+
+Plugin uses ~20k tokens. Disable after analysis:
+
+```bash
+/plugin disable catalyst-debugging
+```
+
+---
+
+**See also**: `/debug-production-error`, `/error-impact-analysis`