Tree-sitter Analyzer デバッグガイド

May 30, 2026 · View on GitHub

概要

Tree-sitter Analyzerのログ設定改善機能により、開発者とユーザーは詳細なデバッグ情報を取得できるようになりました。このガイドでは、効果的なデバッグ手順と環境変数の使用方法について説明します。

🔧 環境変数による制御

基本的なログ制御

環境変数	説明	デフォルト値	使用例
`LOG_LEVEL`	メインロガーのログレベル	`WARNING`	`DEBUG`, `INFO`, `WARNING`, `ERROR`
`TREE_SITTER_ANALYZER_ENABLE_FILE_LOG`	ファイルログの有効化	`false`	`true`
`TREE_SITTER_ANALYZER_LOG_DIR`	ログファイルの出力ディレクトリ	システム一時ディレクトリ	`/var/log/tree-sitter`
`TREE_SITTER_ANALYZER_FILE_LOG_LEVEL`	ファイルログのレベル	メインロガーと同じ	`DEBUG`, `INFO`, `WARNING`, `ERROR`

設定例

1. 基本的なデバッグ設定

export LOG_LEVEL=DEBUG
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true

2. カスタムログディレクトリ設定

export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_LOG_DIR=/home/user/logs/tree-sitter
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

3. 本番環境での最小ログ設定

export LOG_LEVEL=ERROR
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=WARNING

🐛 デバッグ手順

1. MCPサーバーのデバッグ

Claude Desktopでのデバッグ設定

~/Library/Application Support/Claude/claude_desktop_config.jsonに以下を追加（Windows: %APPDATA%\Claude\claude_desktop_config.json、Linux: ~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": [
        "run", "--with", "tree-sitter-analyzer[mcp]",
        "python", "-m", "tree_sitter_analyzer.mcp.server"
      ],
      "env": {
        "TREE_SITTER_PROJECT_ROOT": "/path/to/your/project",
        "TREE_SITTER_ANALYZER_ENABLE_FILE_LOG": "true",
        "TREE_SITTER_ANALYZER_FILE_LOG_LEVEL": "DEBUG",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

ログファイルの確認

ログファイルの場所を確認：

# デフォルトの場所（システム一時ディレクトリ）
ls /tmp/tree_sitter_analyzer.log  # Linux/macOS
dir %TEMP%\tree_sitter_analyzer.log  # Windows

リアルタイムでログを監視：
```
tail -f /tmp/tree_sitter_analyzer.log
```

2. CLIツールのデバッグ

デバッグモードでの実行

# 環境変数を設定してCLIを実行
export LOG_LEVEL=DEBUG
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true

uv run python -m tree_sitter_analyzer examples/BigService.java --advanced

詳細なパフォーマンス分析

# パフォーマンスログも有効化
export LOG_LEVEL=DEBUG
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

uv run tree-sitter-analyzer examples/BigService.java --table full

3. 一般的な問題のトラブルシューティング

問題1: MCPサーバーが起動しない

症状: Claude DesktopでMCPサーバーが認識されない

デバッグ手順:

ログファイルを有効化
Claude Desktopを再起動
ログファイルでエラーメッセージを確認

export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

問題2: ファイル解析が失敗する

症状: 特定のファイルの解析でエラーが発生

デバッグ手順:

DEBUGレベルでログを有効化
問題のファイルを単独で解析
エラーの詳細を確認

export LOG_LEVEL=DEBUG
export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true

uv run tree-sitter-analyzer problematic_file.java --advanced

問題3: パフォーマンスが遅い

症状: 大きなファイルの解析に時間がかかる

デバッグ手順:

パフォーマンスログを有効化
処理時間を測定
ボトルネックを特定

export TREE_SITTER_ANALYZER_ENABLE_FILE_LOG=true
export TREE_SITTER_ANALYZER_FILE_LOG_LEVEL=DEBUG

time uv run tree-sitter-analyzer large_file.java --advanced

📊 ログ出力の理解

ログレベルの説明

DEBUG: 詳細な実行情報、変数の値、内部状態
INFO: 一般的な実行情報、処理の開始/終了
WARNING: 警告メッセージ、非致命的な問題
ERROR: エラーメッセージ、処理の失敗

ログメッセージの例

2025-10-16 12:00:00,123 - tree_sitter_analyzer - INFO - MCP server starting with project root: /path/to/project
2025-10-16 12:00:00,124 - tree_sitter_analyzer - DEBUG - File logging enabled: /tmp/tree_sitter_analyzer.log
2025-10-16 12:00:01,456 - tree_sitter_analyzer.performance - DEBUG - File analysis: 0.1234s - lines: 1419, elements: 85

🔍 高度なデバッグテクニック

1. 条件付きログ出力

特定の条件でのみ詳細ログを出力：

# 大きなファイルのみDEBUGログを出力
if [ $(wc -l < "$FILE") -gt 1000 ]; then
    export LOG_LEVEL=DEBUG
else
    export LOG_LEVEL=INFO
fi

2. ログローテーション

長時間実行時のログファイル管理：

# ログファイルのサイズ制限
export TREE_SITTER_ANALYZER_LOG_DIR=/var/log/tree-sitter
# logrotateを使用してローテーション設定

3. 構造化ログ分析

ログファイルからの情報抽出：

# エラーメッセージのみ抽出
grep "ERROR" /tmp/tree_sitter_analyzer.log

# パフォーマンス情報の抽出
grep "performance" /tmp/tree_sitter_analyzer.log | grep -o "[0-9]\+\.[0-9]\+s"

# 特定のファイルの処理時間
grep "File analysis" /tmp/tree_sitter_analyzer.log | grep "BigService.java"

🚨 注意事項

セキュリティ

ログファイルには機密情報が含まれる可能性があります
本番環境では適切なログレベルを設定してください
ログファイルのアクセス権限を適切に設定してください

パフォーマンス

DEBUGレベルのログは大量の出力を生成します
ファイルログは若干のパフォーマンス影響があります
必要に応じてログレベルを調整してください

ストレージ

ログファイルは時間とともに大きくなります
定期的なクリーンアップを検討してください
ディスク容量を監視してください

📞 サポート

問題が解決しない場合は、以下の情報を含めてIssueを作成してください：

使用した環境変数の設定
実行したコマンド
エラーメッセージ
ログファイルの関連部分
環境情報（OS、Pythonバージョンなど）

🔗 関連ドキュメント

README.md - 基本的な使用方法
CONTRIBUTING.md - 開発者向けガイド
トラブルシューティングガイド - 一般的な問題の解決方法