ndjson-local-log-triage-mcp

🪵 ndjson-local-log-triage-mcp

你的服务刚刚崩溃。日志文件有 2GB。你的 AI Agent 无能为力。

MCP 服务，可流式解析 NDJSON 日志文件，无需将文件载入内存——按模式筛选、通过 Z-score 分析检测错误激增，并按时间窗口汇总严重程度时间线。

---

🤔 问题

凌晨 3 点，服务崩溃了。日志文件是 app.log.ndjson，大小有 2GB。你让 Agent 查找凌晨 03:17 左右错误激增的原因。Agent 无法读取 2GB 的文件，甚至无法尝试。

ndjson-local-log-triage-mcp 逐行流式读取文件——绝不将文件载入内存——并为 Agent 提供所需的日志片段。

---

🛠️ 工具

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-score 的频率分析。按时间窗口对错误分桶，计算均值 + 标准差，并标记错误率异常偏高的时间窗口。

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-score 异常告警，并设置堆内存保护限制。通过标准 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 Log Data Model 结构。

---

⚡ 安装

{
  "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