enhanced-telemetry（增强遥测）

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

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

# 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