Enhanced Telemetry v2 Skill

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": ["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

Check hooks configured:

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

Test script manually:

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

Check Loki receiving data:

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

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

Agent Skills: Enhanced Telemetry v2

Install this agent skill to your local

Skill Files