Trace Interpretation Guide

Overview

ctx-monitor traces are JSONL files stored in .claude/ctx-monitor/traces/ containing structured event records. Each line is a complete JSON object representing a single execution event.

Event Structure

Every trace event contains these core fields:

{
  "event_id": "unique-uuid",
  "session_id": "session-uuid",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "event_type": "PreToolUse|PostToolUse|SessionStart|...",
  "status": "pending|success|error",
  "tool_name": "Write|Edit|Bash|...",
  "args_preview": "truncated arguments (max 500 chars)",
  "error_message": "error details if status is error"
}

Event Types

SessionStart

Marks beginning of a Claude Code session.

• •Fields: session_id, cwd, timestamp
• •Status: started

SessionEnd

Marks end of a session.

• •Fields: session_id, timestamp
• •Status: ended

PreToolUse

Captured before a tool executes.

• •Fields: tool_name, args_preview, tool_use_id
• •Status: pending
• •Use: Identify which tools were called and with what arguments

PostToolUse

Captured after a tool completes.

• •Fields: tool_name, args_preview, result_preview, duration_ms
• •Status: success or error
• •Use: Identify failures, performance issues, success rates

SubagentStop

Captured when a subagent (Task tool) finishes.

• •Fields: reason
• •Status: completed
• •Use: Track subagent lifecycle and completion reasons

Stop

Captured when the main agent stops.

• •Fields: reason
• •Status: completed
• •Use: Understand why the agent stopped (completion, error, user interrupt)

Reading Trace Files

File Naming

session_{session_id}_{timestamp}.jsonl

Sessions Index

.claude/ctx-monitor/traces/sessions.json contains metadata:

{
  "sessions": [
    {
      "session_id": "abc123",
      "started_at": "2024-01-15T10:00:00Z",
      "cwd": "/project/path",
      "event_count": 150
    }
  ]
}

Parsing JSONL

# View all events
cat session_abc123.jsonl | jq .

# Filter by event type
cat session_abc123.jsonl | jq 'select(.event_type == "PostToolUse")'

# Filter errors only
cat session_abc123.jsonl | jq 'select(.status == "error")'

# Count by event type
cat session_abc123.jsonl | jq -s 'group_by(.event_type) | map({type: .[0].event_type, count: length})'

Common Failure Patterns

Intermittent Failures

Pattern: Same tool succeeds sometimes and fails others. Indicators:

• •Tool appears with both success and error status
• •No clear pattern in arguments Causes: Network issues, race conditions, resource contention Solution: Check timing, add retries, verify external dependencies

Hook Not Firing

Pattern: Expected event missing from trace. Indicators:

• •PreToolUse present but no PostToolUse
• •SessionStart without expected hook context Causes: Hook configuration error, matcher not matching, timeout Solution: Verify hooks.json, check matcher patterns, increase timeout

Cascade Failures

Pattern: One error leads to multiple subsequent errors. Indicators:

• •First error followed by many related errors
• •Error messages reference same resource Causes: Missing dependency, broken state, insufficient error handling Solution: Fix root cause, add error boundaries

Performance Degradation

Pattern: Increasing duration_ms over time. Indicators:

• •Same tool takes longer in later events
• •Memory-related errors appear Causes: Memory leak, resource exhaustion, large context Solution: Profile execution, optimize tool usage, compact context

Missing Events

Pattern: Gaps in event sequence. Indicators:

• •PreToolUse without matching PostToolUse
• •SessionStart without SessionEnd Causes: Crash, unhandled exception, force quit Solution: Check for crashes, add error handling

Troubleshooting Checklist

1. •

   Verify monitoring is active

   • •Check .claude/ctx-monitor/config.json has "enabled": true
   • •Confirm hooks are loaded with /hooks command
2. •

   Check trace file exists

   • •List files in .claude/ctx-monitor/traces/
   • •Verify session_id matches current session
3. •

   Analyze error distribution

   • •Count errors per tool
   • •Calculate error rate percentage
   • •Identify error clustering
4. •

   Review timeline

   • •Sort events by timestamp
   • •Look for gaps or anomalies
   • •Correlate with external events
5. •

   Compare with baseline

   • •Use /ctx-monitor:diff against known-good session
   • •Identify what changed

Analysis Agents

ctx-monitor provides specialized agents for different analysis needs:

quick-validator (Haiku)

Model: Haiku (fast, cost-efficient) Purpose: Deterministic validation tasks

Use for:

• •Schema validation
• •Event counting
• •Timestamp verification
• •Integrity checks
• •Corruption detection

Example triggers:

• •"validate my traces"
• •"how many events in my traces?"
• •"check if trace files are corrupted"

Escape mechanism: If quick-validator detects anomalies requiring reasoning (error rate > 10%, orphan events, timing issues), it will stop and suggest using trace-analyzer.

trace-analyzer (inherit)

Model: Inherits from session (user controls via /model) Purpose: Deep analysis requiring reasoning

Use for:

• •Pattern identification
• •Root cause analysis
• •Event correlation
• •Remediation recommendations

Example triggers:

• •"analyze my traces"
• •"why are there errors?"
• •"find issues in execution"

Best practice: For complex analysis, set /model opus before invoking.

Recommended Workflow

1. Start with quick-validator for fast validation
   └─ Uses Haiku (cheap, fast)
   └─ If anomalies detected → suggests next step

2. For deep analysis, use trace-analyzer
   └─ Set model first: /model sonnet or /model opus
   └─ Run trace-analyzer for reasoning tasks

Using Analysis Tools

Generate Report

/ctx-monitor:report --format md

Compare Sessions

/ctx-monitor:diff --last 2

Run Audits

/ctx-monitor:audit --type all

Export for Support

/ctx-monitor:export-bundle --anonymize

References

For detailed patterns and advanced techniques, see:

• •references/event-types.md - Complete event type documentation
• •references/common-failures.md - Expanded failure pattern catalog