ndjson-local-log-triage-mcp

Transmite el triaje de registros NDJSON sin cargar archivos de gigabytes en el contexto.

GitHubPrueba este MCPPatrocinado

Documentación

🪵 ndjson-local-log-triage-mcp

npm CI License: MIT

Tu servicio acaba de fallar. El archivo de registro es de 2GB. Tu agente de IA no puede ayudar.

Servidor MCP que procesa archivos de registro NDJSON en streaming sin cargarlos en memoria — filtra por patrón, detecta picos de errores mediante análisis de puntuación Z, resume líneas de tiempo de severidad por ventana de tiempo.

🤔 El problema

Un servicio falla a las 3am. El archivo de registro es app.log.ndjson y tiene 2GB. Le pides a tu agente que encuentre qué causó el pico de errores alrededor de las 03:17. El agente no puede leer 2GB. Ni siquiera puede intentarlo.

ndjson-local-log-triage-mcp procesa el archivo línea por línea — nunca lo carga en memoria — y le da al agente exactamente la porción que necesita.

🛠️ Herramientas

query_log_pattern

Filtra entradas de registro por coincidencia de campo/valor. Devuelve hasta N entradas coincidentes, procesando el archivo en streaming sin cargarlo por completo. Pasa lineStartPattern (por ejemplo, "^{") para reconstruir trazas de pila multilínea que el analizador predeterminado descarta silenciosamente.

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

Análisis de frecuencia Z-score. Agrupa errores por ventana de tiempo, calcula la media + desviación estándar, y marca ventanas donde la tasa de error es anómalamente alta.

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

Agregación cronológica de conteos de errores, advertencias e información por ventana de tiempo. Visualización rápida de dónde está el incidente.

Pasa adaptive: true para ajustar automáticamente el tamaño del cubo a la densidad real de eventos y acercar la ventana de error máximo con una resolución 10 veces más fina.

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

Reconstruye una traza distribuida a partir de múltiples archivos de registro NDJSON. Dado un trace_id, recopila todos los eventos correlacionados en orden cronológico en todos los archivos y muestra los servicios involucrados y la duración total.

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

Analiza un archivo de registro para inferir su formato de envoltura (NDJSON, Syslog, registros de contenedores de Kubernetes) y extraer esquemas de tipos, identificando claves polimórficas, patrones de marca de tiempo y campos de severidad.

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

group_semantic_patterns

Agrupa dinámicamente mensajes de registro utilizando el algoritmo de análisis Drain basado en árbol de profundidad fija para aislar plantillas de registro distintas y analizar sus distribuciones de parámetros (variaciones de comodín).

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

Inicia el seguimiento de registros en segundo plano con alertas de anomalías Z-score en tiempo real sobre picos de frecuencia de errores y límites de protección de memoria heap. Envía notificaciones directamente a través de canales JSON-RPC estándar.

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

Una puerta de enlace unificada para consultar proveedores de registros centrales (Datadog, Splunk, Elasticsearch), convirtiendo patrones de búsqueda a dialectos específicos del proveedor y mapeando la salida a la estructura estandarizada del Modelo de Datos de Registros de OpenTelemetry.

⚡ Configuración

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

🚀 Uso

"Analiza /var/log/app.log.ndjson — resume la línea de tiempo de errores en ventanas de 5 minutos, detecta cualquier pico anómalo y muéstrame las entradas de error alrededor del pico."

Funciona muy bien junto con:

📦 Enlaces

Licencia

MIT