Agent skill

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/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

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

logql
# 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

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

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

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

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

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

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

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

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

  2. Test script manually:

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

  3. Check Loki receiving data:

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

  4. Check Loki has enhanced data:

    bash
    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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results