o11y-hook-debug

name	o11y-hook-debug
description	Langfuse フック（langfuse_hook.py）のデバッグ実行と診断を行う。フック関連のトラブルシューティング専用コマンド。
disable-model-invocation	true

o11y-hook-debug — Langfuse フックデバッグ

フックをデバッグモードで手動実行し、よくある失敗パターンを自動診断して問題を特定する。

手順

1. 事前チェック（問題の絞り込み）

以下を確認してから実行する。問題がここで特定できれば、フック実行をスキップして診断結果だけ報告してよい。

cat ~/.claude/settings.json | python3 -c "
import json, sys
s = json.load(sys.stdin)
env = s.get('env', {})
print('TRACE_TO_LANGFUSE:', env.get('TRACE_TO_LANGFUSE', '(未設定)'))
print('LANGFUSE_PUBLIC_KEY:', env.get('LANGFUSE_PUBLIC_KEY', '(未設定)')[:20] + '...' if env.get('LANGFUSE_PUBLIC_KEY') else '(未設定)')
print('LANGFUSE_BASE_URL:', env.get('LANGFUSE_BASE_URL', '(未設定)'))
hooks = s.get('hooks', {}).get('Stop', [])
hook_cmds = [hh.get('command','') for h in hooks for hh in h.get('hooks',[]) if 'langfuse' in hh.get('command','')]
print('Stop フック:', hook_cmds[0] if hook_cmds else '(未登録)')
"

よくある失敗パターンと即時診断:

症状	診断	対処
TRACE_TO_LANGFUSE が未設定または true 以外	フックは無効	~/.claude/settings.json の env に "TRACE_TO_LANGFUSE": "true" を手動追加
LANGFUSE_PUBLIC_KEY が未設定	キー未設定	uv run manage.py setup を再実行
Stop フックが未登録	フック自体が動いていない	uv run manage.py setup を再実行

2. フックをデバッグモードで実行

事前チェックで問題が特定できなかった場合、デバッグ実行する。

cd ~/Projects/agent-o11y && CC_LANGFUSE_DEBUG=true uv run claude-hooks/langfuse_hook.py <<'EOF'
{}
EOF

3. ログの末尾を確認

tail -20 ~/.claude/state/langfuse_hook.log 2>/dev/null || echo "ログファイルが存在しません"

4. キー整合性の確認

teardown → setup 後にフックが動かない場合、セッションにキャッシュされた古いキーが原因のことがある。

echo "=== ログの最終接続キー ==="
grep -a "pk=" ~/.claude/state/langfuse_hook.log 2>/dev/null | tail -1

echo "=== settings.json の現在のキー ==="
cat ~/.claude/settings.json | python3 -c "
import json,sys; s=json.load(sys.stdin)
print(s.get('env',{}).get('LANGFUSE_PUBLIC_KEY','(未設定)')[:20]+'...')
"

出力フォーマット

## Langfuse フック診断

### 事前チェック
| 項目                | 値                                      | 状態    |
|--------------------|-----------------------------------------|---------|
| TRACE_TO_LANGFUSE  | true                                    | ✓ 有効  |
| LANGFUSE_PUBLIC_KEY| pk-lf-xxxx...                           | ✓ 設定済|
| LANGFUSE_BASE_URL  | http://localhost:3000                   | ✓ 設定済|
| Stop フック        | uv run ~/.claude/hooks/langfuse_hook.py | ✓ 登録済|

### デバッグ実行結果
（実行ログをそのまま表示）

### ログ末尾
（tail -20 の出力をそのまま表示）

### キー整合性
（一致 / 不一致 を明記）

---
✓ フックは正常に動作しています   ← または ✗ 問題あり: <原因>

最終行は必ず ✓ フックは正常に動作しています か ✗ 問題あり: <原因の要約> にする。

補足

• TRACE_TO_LANGFUSE は manage.py setup で自動設定されない。手動で ~/.claude/settings.json の env セクションに追加が必要
• キャッシュ問題: Claude Code はセッション開始時に settings.json の env をキャッシュする。teardown → setup でキーが変わっても、/resume で再開したセッションには古いキーが残る。フックスクリプト自体は毎回 settings.json を直接読むため影響を受けないが、ログに古いキーが出る場合は新規セッション（claude コマンドで起動）で確認する
• フックログのデフォルトパス: ~/.claude/state/langfuse_hook.log
• フックの状態ファイル: ~/.claude/state/langfuse_state.json（増分読み込みのオフセット管理）