enhanced-telemetry

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

Hook	Event Type	What's Captured
SessionStart	session_start	Source, permission mode, git info
SessionEnd	session_end	Duration, turns, tools, errors, subagents
UserPromptSubmit	user_prompt	Pattern, length, tokens, prompt hash
PreToolUse	tool_call	Tool name, details, sequence position
PostToolUse	tool_result	Status, response size, errors
SubagentStop	subagent_complete	Subagent count
PermissionRequest	permission_request	Notification type
PreCompact	context_compact	Trigger (manual/auto), token estimate
Notification	notification	Notification type
Stop	session_end	Same as SessionEnd

Configuration

Settings file: .claude/settings.json

{
  "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" 
     
     
     
     
  

Viewing Data

Grafana Dashboards

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

LogQL Queries

# 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

Files

.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:

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

2. Test script manually:

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

3. Check Loki receiving data:

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

4. Check Loki has enhanced data:

   curl -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