Enhanced Telemetry v2 通过 Claude Code 全部 10 个可用钩子采集全面的使用指标，提供超出默认 OTEL 遥测的深度可观测性。
用途
该技能用于对 Claude Code 的使用过程进行细粒度监控与分析，覆盖会话、对话、工具、子代理、上下文、仓库和权限等多个维度，帮助了解编码会话的实际运行情况。
主要能力
会话分析：采集会话生命周期（开始/结束）、会话时长、会话来源（startup/resume/clear/compact）、会话终止原因、权限模式。
对话分析：每会话轮次数量、提示模式（question/debugging/creation/ultrathink）、提示长度与 token 估算、对话风格分布。
工具分析：工具调用频率、工具调用序列（上一个 → 当前）、工具错误率、响应大小与 token 估算、访问的文件类型。
子代理分析：每会话生成的子代理数量、子代理类型（Explore、Plan、general-purpose 等）、子代理完成情况跟踪。
上下文分析：估算 token 使用量、上下文窗口利用率百分比、上下文压缩事件（手动 vs 自动）、token 累积跟踪。
仓库分析：按仓库统计活动、按项目统计工具使用、分支级别跟踪。
权限分析：权限请求、权限类型、通知跟踪。
10 个已插桩的钩子
SessionStart（session_start）：来源、权限模式、git 信息。 SessionEnd（session_end）：时长、轮次、工具、错误、子代理。 UserPromptSubmit（user_prompt）：模式、长度、token、提示哈希。 PreToolUse（tool_call）：工具名称、详情、序列位置。 PostToolUse（tool_result）：状态、响应大小、错误。 SubagentStop（subagent_complete）：子代理数量。 PermissionRequest（permission_request）：通知类型。 PreCompact（context_compact）：触发方式（手动/自动）、token 估算。 Notification（notification）：通知类型。 Stop（session_end）：与 SessionEnd 相同。
使用方式
配置位于 .claude/settings.json，通过 hooks 字段为上述 10 个事件分别注册调用 python3 .claude/hooks/enhanced-telemetry.py 并传入对应事件名。PreToolUse 与 PostToolUse 使用 matcher ".*" 匹配所有工具。
查看数据：
Grafana 仪表盘：Enhanced Analytics（http://localhost:3000/d/claude-code-enhanced）、Deep Analytics（http://localhost:3000/d/claude-code-deep）。
LogQL 查询示例：
- 全部增强遥测：{job="claude_code_enhanced"} | json
- 会话分析：{job="claude_code_enhanced", event_type="session_end"} | json
- 工具调用：{job="claude_code_enhanced", event_type="tool_call"} | json
- 提示模式：sum by (pattern) (count_over_time({job="claude_code_enhanced", event_type="user_prompt"} | json [24h]))
- 技能使用：{job="claude_code_enhanced", event_type="skill_usage"} | json
- 上下文利用率：{job="claude_code_enhanced", event_type="context_utilization"} | json
- 工具序列：{job="claude_code_enhanced", event_type="tool_call"} | json | line_format "{{.previous_tool}} → {{.tool_name}}"
- 子代理跟踪：{job="claude_code_enhanced", event_type="tool_call", tool="Task"} | json
- 错误分析：{job="claude_code_enhanced", event_type="tool_result", status="error"} | json
- 上下文压缩：{job="claude_code_enhanced", event_type="context_compact"} | json
事件 schema 涵盖 session_start、session_end、user_prompt、tool_call、tool_result、context_utilization、context_compact 等，字段包括 session_id、source、permission_mode、cwd、git 信息、duration_seconds、turn_count、tools_used、tool_sequence、subagents_spawned、error_count、prompt_length、estimated_tokens、prompt_hash、patterns、tool_name、tool_use_id、tool_details、sequence_position、previous_tool、response_length、is_error、error_type、context_percentage、trigger 等。
文件结构：.claude/hooks/enhanced-telemetry.py（主遥测脚本 v2）、.claude/settings.json（钩子配置）、.claude/skills/enhanced-telemetry/SKILL.md（文档）。
适用场景
适用于需要对 Claude Code 会话进行深度可观测性分析的场景，例如统计工具使用与错误、跟踪子代理与上下文消耗、按仓库或分支分析活动，以及与其他可观测性技能（observability-analyzer、observability-pattern-detector、observability-alert-manager、skill-improvement-from-observability）集成使用。
限制与要求
需要 Python 3.x（在 PATH 中）、Loki 运行于 localhost:3100、Claude Code 钩子已启用。
故障排查：若仪表盘无数据，可检查钩子配置（cat .claude/settings.json | grep enhanced-telemetry）、手动测试脚本（echo '{"tool_name":"Test"}' | python3 .claude/hooks/enhanced-telemetry.py PreToolUse）、检查 Loki 是否接收数据（curl -s "http://localhost:3100/loki/api/v1/labels"，应包含 event_type、tool、repo、pattern 等）、检查 Loki 是否有增强数据（curl -s "http://localhost:3100/loki/api/v1/query?query={job="claude_code_enhanced"}&limit=5"）。若钩子未运行，确保从包含 .claude/settings.json 的项目目录启动 Claude Code，校验 settings.json 为合法 JSON（python3 -m json.tool .claude/settings.json），确认 Python 可用（which python3）。若脚本报错，检查脚本权限（chmod +x .claude/hooks/enhanced-telemetry.py），手动运行并查看 stderr 调试输出。