ndjson-local-log-triage-mcp

🪵 ndjson-local-log-triage-mcp

サービスがクラッシュしました。ログファイルは2GBです。AI エージェントには対処できません。

ログファイルをメモリに読み込まずにストリーム解析する MCP サーバーです。パターンによる絞り込み、Z スコア分析によるエラースパイクの検出、時間枠ごとの重大度タイムラインの要約ができます。

---

🤔 問題

午前3時にサービスがクラッシュしました。ログファイルは app.log.ndjson で、サイズは2GBです。午前3時17分ごろにエラーが急増した原因を見つけるよう、エージェントに頼みます。エージェントは2GBのファイルを読み取れません。試すことすらできません。

ndjson-local-log-triage-mcp はファイルを1行ずつストリーミングし、メモリに読み込むことなく、エージェントに必要な部分だけを提供します。

---

🛠️ ツール

query_log_pattern

フィールドと値の一致によってログエントリを絞り込みます。ファイル全体を読み込まずにストリーミングし、一致するエントリを最大 N 件返します。既定のパーサーが暗黙に破棄する複数行のスタックトレースを再構成するには、lineStartPattern（例："^{"）を渡します。

Log Query Results
  File:        /var/log/app.log.ndjson
  Filter:      service contains "auth"
  Lines read:  847,293
  Matches:     50 (limit 50 reached)

{"timestamp":"2025-01-15T03:17:02Z","level":"error","service":"auth","msg":"token validation failed","userId":"u_abc123"}
...

detect_error_anomalies

Z スコアによる頻度分析です。時間枠ごとにエラーを集計し、平均値と標準偏差を計算して、エラー率が異常に高い時間枠を検出します。

Error Anomaly Detection
  File:            /var/log/app.log.ndjson
  Window:          5min
  Z-score cutoff:  2.0
  Baseline:        mean=3.2 errors/window, stdDev=1.8
  Anomalies found: 2

  [z=4.71] 2025-01-15T03:15:00.000Z  23 errors
  [z=2.33] 2025-01-15T03:20:00.000Z  9 errors

summarize_log_timeline

時間枠ごとにエラー、警告、情報の件数を時系列で集計します。インシデントが発生している箇所をすばやく視覚的に把握できます。

adaptive: true を渡すと、実際のイベント密度に合わせてバケットサイズを自動調整し、エラーのピーク時間枠を10倍細かい解像度で拡大表示します。

Log Timeline Summary
  File:        /var/log/app.log.ndjson
  Window:      5min
  Buckets:     48

  Time (UTC)                 Errors  Warnings  Info  Other
  ─────────────────────────────────────────────────────────
    2025-01-15 03:00:00Z          2         8   142      0
    2025-01-15 03:05:00Z          1         5   138      0
    2025-01-15 03:10:00Z          3         9   141      0
  ! 2025-01-15 03:15:00Z         23        14   119      0
    2025-01-15 03:20:00Z          9        11   133      0

correlate_request

複数の NDJSON ログファイルから分散トレースを再構成します。trace_id を指定すると、すべてのファイルから関連するイベントを収集して時系列順に並べ、関係するサービスと合計所要時間を提示します。

Request Correlation
  Trace ID:          trace-8f7a9b2c
  Files scanned:     2
  Events found:      10
  Services involved: api, worker
  Duration:          890ms

[2025-01-15T14:00:00.001Z] api           {"level":"info","msg":"incoming request",...}
[2025-01-15T14:00:00.045Z] api           {"level":"info","msg":"auth token validated",...}
[2025-01-15T14:00:00.112Z] worker        {"level":"info","msg":"job queued",...}
...

discover_log_schema

ログファイルを分析してラッパー形式（NDJSON、Syslog、Kubernetes コンテナーログ）を推定し、型スキーマを抽出します。多態性のあるキー、タイムスタンプのパターン、重大度フィールドを特定します。

{
  "fileFormat": "NDJSON",
  "detectedKeys": {
    "timestamp": { "type": "string", "format": "date-time", "isChronologicalIndex": true },
    "level": { "type": "string", "isSeverityField": true, "possibleValues": ["info", "error"] }
  }
}

group_semantic_patterns

固定深度のツリーベースのDrain 解析アルゴリズムを使用してログメッセージを動的にクラスタリングし、個別のログテンプレートを分離するとともに、そのパラメーター分布（ワイルドカードによる変動）を分析します。

Processed Logs: 1500
Unique Patterns: 2

- Template: "connection failed from * port *"
  Occurrences: 1200
  Parameters:
    - param_0 (client_ip): 192.168.1.1 (80%), 10.0.0.5 (20%)

start_live_triage

エラー頻度の急増をリアルタイムの Z スコアで検出して通知するバックグラウンドのログテーリングを開始します。ヒープメモリ保護の上限も設定できます。標準の JSON-RPC チャネルを通じて通知を直接配信します。

{
  "method": "notifications/triage",
  "params": {
    "type": "anomaly",
    "message": "Live Anomaly Detected: 45 errors in current window (Z-score: 3.52)",
    "z_score": 3.52,
    "error_count": 45
  }
}

query_external_logs

中央ログプロバイダー（Datadog、Splunk、Elasticsearch）にクエリを送信する統合ゲートウェイです。検索パターンを各ベンダー固有の形式に変換し、出力を標準化されたOpenTelemetry ログデータモデルの構造に対応付けます。

---

⚡ セットアップ

{
  "mcpServers": {
    "log-triage": {
      "command": "npx",
      "args": ["-y", "ndjson-local-log-triage-mcp"]
    }
  }
}

---

🚀 使用方法

「/var/log/app.log.ndjson を分析して、エラーのタイムラインを5分間隔で要約し、異常な急増があれば検出して、その急増前後のエラーエントリを表示してください。」

次のツールと組み合わせると便利です。

• release-readiness-triage-mcp — リリース前の CI 失敗のトリアージ
• env-secret-exposure-analyzer-mcp — シークレットの漏えいスキャン

---

📦 リンク

• npm： npmjs.com/package/ndjson-local-log-triage-mcp
• GitHub： github.com/vola-trebla/ndjson-local-log-triage-mcp

ライセンス

MIT