Learn-skills.dev enhanced-telemetry

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.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/adaptationio/skrillz/enhanced-telemetry" ~/.claude/skills/neversight-learn-skills-dev-enhanced-telemetry && rm -rf "$T"

manifest: data/skills-md/adaptationio/skrillz/enhanced-telemetry/SKILL.md

source content

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