log-reducer

Log Reducer

AI コーディングエージェントは、生のログを読むために何千ものトークンを消費しています。DEBUG の大量出力、ヘルスチェック、重複行、フレームワークのスタックフレーム、UUID。これらのトークンは、セッションの残り時間には使えなくなります。エージェントが思考に使える余裕は減り、生成するコードの質が下がり、コンテキスト上限にも早く達してしまいます。

Log Reducer は、ログと AI の間に位置します。ログファイルを重要な情報、つまりエラー、警告、状態の変化、一意のイベントだけに絞り込み、通常はトークンを 70～90％削減します。生のログが AI のコンテキストに入ることはありません。

MCP サーバー（AI がファイルパスを指定して reduce_log を呼び出します）または CLI（あらゆるログをパイプで渡せます）として動作します。API キーもネットワーク呼び出しも不要です。決定論的なテキスト変換を瞬時に実行します。

例

FastAPI の開発サーバーを実行しています。画面を操作して 500 エラーを発生させ、ターミナルの出力をファイルにコピーします。ファイルは 218 行あり、その大部分はフレームワークのスタックトレースです。

218 lines, 1185 tokens  →  51 lines, 310 tokens  (74% reduction)

このツールがスタックトレースをどのように処理するか見てみましょう。uvicorn、starlette、FastAPI のフレームを含む、実際の Python 例外グループです。

処理前 — スタックトレースは 95 行で、C:\Users\...\.venv\Lib\site-packages\ のパスがすべて表示されています。

    |   File "C:\Users\imank\projects\video-editor\src\backend\.venv\Lib\site-packages\
             uvicorn\protocols\http\httptools_impl.py", line 426, in run_asgi
    |     result = await app(  # type: ignore[func-returns-value]
    |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |   File "C:\Users\imank\projects\video-editor\src\backend\.venv\Lib\site-packages\
             uvicorn\middleware\proxy_headers.py", line 84, in __call__
    |     return await self.app(scope, receive, send)
    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ... 85 more framework lines ...
    |   File "C:\Users\imank\projects\video-editor\src\backend\app\routers\exports.py",
             line 745, in list_unacknowledged_exports

処理後 — 自分のコードは残り、フレームワークの部分は折りたたまれ、重複するトレースバックは削除されています。

    |   [... 10 framework frames (uvicorn, fastapi, starlette, contextlib) omitted ...]
    |   File "app/middleware/db_sync.py", line 107, in dispatch
    |     response = await call_next(request)
    |   [... 6 framework frames (starlette, contextlib) omitted ...]
    |   File "app/main.py", line 97, in dispatch
    |     response = await call_next(request)
    |   [... 16 framework frames (starlette, fastapi) omitted ...]
    |   File "app/routers/exports.py", line 745, in list_unacknowledged_exports
    |     exports=[
    |   File "app/routers/exports.py", line 746, in <listcomp>
    |     ExportJobResponse(
    | pydantic_core._pydantic_core.ValidationError: 1 validation error for ExportJobResponse
    | project_id
    |   Input should be a valid integer [type=int_type, input_value=None, input_type=NoneType]

Traceback (most recent call last):
  [... duplicate traceback omitted ...]

バグは明らかです。exports.py:745 で、整数を期待する Pydantic モデルに project_id=None を渡しています。フレームワークのフレームは 95 個ではなく 3 個です。C:\Users\...\.venv\ のパスもありません。

(処理前／処理後の全体 | 大きなログにファネルパターンを適用する方法)

セットアップ

ステップ 1 — インストール

npm install -g logreducer

ステップ 2 — プロジェクトに MCP サーバーを追加

プロジェクトのルートで次を実行します。

claude mcp add logreducer -s project -- npx -y logreducer --mcp

これにより、設定が .mcp.json（Claude Code が読み込むファイル）に書き込まれます。手動で追加することもできます。

{
  "mcpServers": {
    "logreducer": {
      "command": "npx",
      "args": ["-y", "logreducer", "--mcp"]
    }
  }
}

ステップ 3 — AI への指示を追加

Claude Code に次のように伝えます。「https://github.com/launch-it-labs/log-reducer/blob/master/docs/agent-integration.md の統合ガイドに従ってください」 — CLAUDE.md に適切な指示を追加し、/logdump スラッシュコマンドを設定します。

正しく動作することを確認します。「利用できる MCP ツールは何ですか？」 — reduce_log が一覧に表示されるはずです。

これで完了です。AI エージェントは、生のログを読む代わりに自動でログを削減するようになります。

使い方

セットアップが完了すれば、コマンドやパラメーターを覚える必要はありません。すべて AI が自動で処理します。知っておくことは 2 つだけです。

AI とログを共有する

ログをクリップボードにコピーしてから、チャットで /logdump と入力します。 生のログは一時ファイルに保存され、自動で削減されます。AI のコンテキストに入ることはありません。ログを共有する際はこの方法をおすすめします。

AI にファイルを指定することもできます。「/var/log/app.log のエラーを確認して」 と伝えると、生のログを読む代わりに reduce_log を呼び出します。

CLI（スクリプトやパイプでの利用）

AI セッションの外で、コマンドラインから直接使用することもできます。

logreducer < app.log > reduced.log
kubectl logs my-pod | logreducer
logreducer --level error --context 10 < app.log

仕組み

以下は、仕組みに興味がある方向けの説明です。Log Reducer を使うために読む必要はありません。

ログに対する処理

影響の大きいものから順に示します。

• ノイズを除去 — ヘルスチェック、ハートビート、プログレスバーを削除します（DEBUG／TRACE 行は保持します。AI は level フィルターで除外するタイミングを選べます）
• スタックトレースを折りたたみ — 80 フレームを、コードのフレームと [... N framework frames omitted ...] にまとめます
• 繰り返し行を集約 — 類似する 6 行を 1 つのテンプレートにまとめ、異なる値を一覧表示します
• ログのプレフィックスを共通化 — timestamp - module - LEVEL を共有する 8 行を、1 つのヘッダーとインデント付きメッセージにまとめます
• 繰り返しブロックを検出 — 同一の 3 行ブロック 5 つを、1 つのブロックと回数にまとめます
• ID を短縮 — UUID、16 進文字列、JWT、トークンを $1、$2、... に置き換えます
• タイムスタンプを簡略化 — 2024-01-15T14:32:01.123Z を 14:32:01 に変換します
• テスト出力を集約 — PASS 行の連続を件数のサマリーにまとめます。FAIL 行は常に保持します
• ドメイン固有の処理 — pip のインストール、Docker レイヤー、HTTP アクセスログ、再試行ブロック、ログエンベロープには、それぞれ専用の集約処理があります

19 個の変換を順番に適用します。ルールベースで決定論的に動作し、API 呼び出しは不要です。オプションの query パラメーターでは、対象を絞った抽出に Claude を使用します（ANTHROPIC_API_KEY が必要です）。

[x7] [CacheWarming] Warmed tail of large video ({N}MB) | N = 2574, 3139, 2897, 3063, 2490, 2996, 3043

複数ターンでの調査

このツールは、一度だけ実行する削減ツールではありません。ファネルパターンに対応しており、AI は大きなログファイルを対象を絞った複数回のパスで調査できます。無差別にログを出力した場合の 5,000 トークン以上に対し、合計約 1,000 トークンで済みます。AI がこの処理を自動で行いますが、内部では次のように動作します。

Step 1: SURVEY → reduce_log({ file, tail: 2000 })           ~50 tokens
  If the reduced output exceeds the threshold (default: 1000 tokens),
  the tool automatically returns an enhanced summary instead of the full
  output: unique errors/warnings with counts, time span, and components.

Step 2: SCAN   → level: "error", limit: 3                   ~200 tokens
  See first 3 errors with context. Note timestamps.

Step 3: ZOOM   → time_range: "13:02:28-13:02:35", before: 50  ~500 tokens
  50 lines leading up to the first error — the causal chain.

Step 4: TRACE  → grep: "pool|conn", time_range: "13:00-13:05",  ~300 tokens
                  limit: 15, context: 0
  Follow the connection pool thread.

合計：約 1,050 トークンです。エージェントはログ全体を読み込むことなく、根本原因（バッチジョブによる接続プールの枯渇）を特定しました。

パラメーターの完全なリファレンスとフィルターの詳細については、docs/agent-integration.md を参照してください。

設計上の判断

• ファイルパスを使うワークフロー — MCP ツールはファイルパスを受け取るため、生のログが AI のコンテキストに入ることはありません。削減後の出力だけが会話に渡されます。
• 行数よりトークン数の削減を優先 — AI のコンテキストウィンドウで重要なのはトークン数であるため、統計は行数ではなくトークン数で報告します。
• 網羅性より汎用性を優先 — 新しい変換は、どれだけ幅広く適用できるかを基準に評価します。特定のアプリケーションのログにしか効果がないパターンは、そのケースを改善できる場合でも、バイアスのリスクとしてフラグを立てて除外します。
• 変換の順序が重要 — 重複排除の前に ID とタイムスタンプを短縮することで、それらの値だけが異なる行を同一にします。プレフィックスを共通化する前にノイズを除去することで、区切り行によってグループ化が妨げられるのを防ぎます。
• 各変換は独立 — 純粋関数として入力を受け取り、文字列を返します。パイプラインのほかの部分に手を加えることなく、簡単に追加、テスト、並べ替えができます。
• 依存関係を最小限に — TypeScript のみで実装し、ランタイム依存関係は 1 つです（@modelcontextprotocol/sdk）。

貢献

最も簡単な貢献方法は、ログファイルを貼り付けることです。 このプロジェクトを Claude Code で開き、チャットにログを貼り付けると、AI がログを分析し、パイプラインが見逃すパターンを特定して、幅広く適用できる修正を実装し、PR を作成します。コードの知識は必要ありません。ログがテスト用のフィクスチャとなり、すべての人にとってツールが改善されます。

Claude Code を使わない場合は、GitHub の Issue からログを送信することもできます。

コードで貢献する場合は、CONTRIBUTING.mdをご覧ください。

ライセンス

MIT