---

name: enhanced-telemetry description: Comprehensive Claude Code telemetry via 10 hooks capturing sessions, conversations, tools, subagents, context, permissions, and repository analytics. Use when analyzing detailed usage patterns beyond default OTEL.

Enhanced Telemetry v2

Captures comprehensive Claude Code metrics via ALL 10 available hooks, providing deep observability beyond default OTEL telemetry.

What It Captures

Session Analytics

• Session lifecycle (start/end)
• Session duration
• Session source (startup/resume/clear/compact)
• Session termination reason
• Permission mode

Conversation Analytics

• Turn count per session
• Prompt patterns (question/debugging/creation/ultrathink)
• Prompt length and token estimates
• Conversation style distribution

Tool Analytics

• Tool call frequency
• Tool sequences (previous → current)
• Tool error rates
• Response sizes and token estimates
• File types accessed

Subagent Analytics

• Subagents spawned per session
• Subagent types (Explore, Plan, general-purpose, etc.)
• Subagent completion tracking

Context Analytics

• Estimated token usage
• Context window utilization percentage
• Context compaction events (manual vs auto)
• Token accumulation tracking

Repository Analytics

• Activity per repository
• Tool usage by project
• Branch-level tracking

Permission Analytics

• Permission requests
• Permission types
• Notification tracking

10 Hooks Instrumented

Configuration

Settings file: .claude/settings.json

Copy{
  "hooks": {
    "SessionStart": ["python3 .claude/hooks/enhanced-telemetry.py SessionStart"],
    "SessionEnd": ["python3 .claude/hooks/enhanced-telemetry.py SessionEnd"],
    "UserPromptSubmit": ["python3 .claude/hooks/enhanced-telemetry.py UserPromptSubmit"],
    "PreToolUse": [{"matcher": ".*", "hooks": ["python3 .claude/hooks/enhanced-telemetry.py PreToolUse"]}],
    "PostToolUse": [{"matcher": ".*", "hooks": ["python3 .claude/hooks/enhanced-telemetry.py PostToolUse"]}],
    "SubagentStop": ["python3 .claude/hooks/enhanced-telemetry.py SubagentStop"],
    "PermissionRequest": ["python3 .claude/hooks/enhanced-telemetry.py PermissionRequest"],
    "PreCompact": ["python3 .claude/hooks/enhanced-telemetry.py PreCompact"],
    "Notification": ["python3 .claude/hooks/enhanced-telemetry.py Notification"],
    "Stop": ["python3 .claude/hooks/enhanced-telemetry.py Stop"]
  }
}

Viewing Data

Grafana Dashboards

• Enhanced Analytics: http://localhost:3000/d/claude-code-enhanced
• Deep Analytics: http://localhost:3000/d/claude-code-deep

LogQL Queries

Copy# All enhanced telemetry
{job="claude_code_enhanced"} | json

# Session analytics
{job="claude_code_enhanced", event_type="session_end"} | json

# Tool calls
{job="claude_code_enhanced", event_type="tool_call"} | json

# Prompt patterns
sum by (pattern) (count_over_time({job="claude_code_enhanced", event_type="user_prompt"} | json [24h]))

# Skill usage
{job="claude_code_enhanced", event_type="skill_usage"} | json

# Context utilization
{job="claude_code_enhanced", event_type="context_utilization"} | json

# Tool sequences
{job="claude_code_enhanced", event_type="tool_call"} | json | line_format "{{.previous_tool}} → {{.tool_name}}"

# Subagent tracking
{job="claude_code_enhanced", event_type="tool_call", tool="Task"} | json

# Error analysis
{job="claude_code_enhanced", event_type="tool_result", status="error"} | json

# Context compaction
{job="claude_code_enhanced", event_type="context_compact"} | json

Event Schemas

session_start

Copy{
  "event": "session_start",
  "session_id": "abc123",
  "source": "startup",
  "permission_mode": "default",
  "cwd": "/mnt/c/data/github/project",
  "timestamp": "2025-11-27T08:00:00Z",
  "git": {"repo_name": "project", "branch": "main"}
}

session_end

Copy{
  "event": "session_end",
  "session_id": "abc123",
  "reason": "prompt_input_exit",
  "duration_seconds": 1847.5,
  "turn_count": 25,
  "tools_used": {"Read": 45, "Edit": 12, "Bash": 8},
  "tool_sequence": ["Read", "Edit", "Bash", "Read"],
  "subagents_spawned": 3,
  "error_count": 2,
  "timestamp": "2025-11-27T08:30:00Z"
}

user_prompt

Copy{
  "event": "user_prompt",
  "turn_number": 5,
  "prompt_length": 256,
  "estimated_tokens": 64,
  "prompt_hash": "a1b2c3d4",
  "patterns": ["question", "debugging"],
  "timestamp": "2025-11-27T08:05:00Z"
}

tool_call

Copy{
  "event": "tool_call",
  "tool_name": "Read",
  "tool_use_id": "xyz789",
  "tool_details": {"file_path": "/src/main.py", "file_type": ".py"},
  "sequence_position": 15,
  "previous_tool": "Glob",
  "timestamp": "2025-11-27T08:05:30Z"
}

tool_result

Copy{
  "event": "tool_result",
  "tool_name": "Read",
  "tool_use_id": "xyz789",
  "response_length": 4500,
  "estimated_tokens": 1125,
  "is_error": false,
  "error_type": null,
  "timestamp": "2025-11-27T08:05:31Z"
}

context_utilization

Copy{
  "event": "context_utilization",
  "estimated_session_tokens": 45000,
  "context_percentage": 22.5,
  "last_content_tokens": 5000,
  "turn_count": 15,
  "timestamp": "2025-11-27T08:10:00Z"
}

context_compact

Copy{
  "event": "context_compact",
  "trigger": "auto",
  "has_custom_instructions": false,
  "session_turn_count": 45,
  "estimated_tokens_before": 180000,
  "timestamp": "2025-11-27T08:15:00Z"
}

Files

Copy.claude/
├── hooks/
│   └── enhanced-telemetry.py       # Main telemetry script (v2)
├── settings.json                    # Hook configurations
└── skills/
    └── enhanced-telemetry/
        └── SKILL.md                 # This documentation

Requirements

• Python 3.x (in PATH)
• Loki running at localhost:3100
• Claude Code hooks enabled

Troubleshooting

No Data in Dashboards

1. Check hooks configured:

   Copycat .claude/settings.json | grep enhanced-telemetry
   

2. Test script manually:

   Copyecho '{"tool_name":"Test"}' | python3 .claude/hooks/enhanced-telemetry.py PreToolUse
   

3. Check Loki receiving data:

   Copycurl -s "http://localhost:3100/loki/api/v1/labels"
   # Should include: event_type, tool, repo, pattern, etc.
   

4. Check Loki has enhanced data:

   Copycurl -s "http://localhost:3100/loki/api/v1/query?query={job=\"claude_code_enhanced\"}&limit=5"
   

Hooks Not Running

• Ensure Claude Code started from project directory with .claude/settings.json
• Check settings.json is valid JSON: python3 -m json.tool .claude/settings.json
• Verify Python available: which python3

Script Errors

• Check script permissions: chmod +x .claude/hooks/enhanced-telemetry.py
• Test with debug output: Run script manually and check stderr

Integration with Other Skills

• observability-analyzer: Uses {job="claude_code_enhanced"} queries
• observability-pattern-detector: Detects patterns in enhanced data
• observability-alert-manager: Alerts on enhanced telemetry events
• skill-improvement-from-observability: Uses enhanced data for insights