Skills
skills/adaptationio/skrillz/enhanced-telemetry

enhanced-telemetry

SKILL.md

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

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
Weekly Installs
1
Repository
adaptationio/skrillz
Installed on
claude-code1