ndjson-local-log-triage-mcp

Transmite triagem de logs NDJSON sem carregar arquivos de gigabytes no contexto

GitHubExperimente este MCPPatrocinado

Documentação

🪵 ndjson-local-log-triage-mcp

npm CI License: MIT

Seu serviço acabou de falhar. O arquivo de log tem 2GB. Seu agente de IA não consegue ajudar.

Servidor MCP que faz parse de arquivos de log NDJSON em streaming sem carregá-los na memória — filtre por padrão, detecte picos de erros via análise de Z-score, resuma linhas do tempo de severidade por janela de tempo.

🤔 O problema

Um serviço falha às 3h da manhã. O arquivo de log é app.log.ndjson e tem 2GB. Você pede ao seu agente para descobrir o que causou o pico de erros por volta das 03:17. O agente não consegue ler 2GB. Ele nem consegue tentar.

ndjson-local-log-triage-mcp faz streaming do arquivo linha por linha — nunca o carregando na memória — e dá ao agente exatamente a fatia que ele precisa.

🛠️ Ferramentas

query_log_pattern

Filtra entradas de log por correspondência de campo/valor. Retorna até N entradas correspondentes, fazendo streaming do arquivo sem carregá-lo inteiramente. Passe lineStartPattern (ex.: "^{") para reconstruir stack traces multilinha descartados silenciosamente pelo parser padrão.

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álise de frequência por Z-score. Agrupa erros por janela de tempo, calcula média + desvio padrão e sinaliza janelas onde a taxa de erros está anormalmente 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

Agregação cronológica de contagens de erros, avisos e informações por janela de tempo. Visual rápido de onde está o incidente.

Passe adaptive: true para dimensionar automaticamente o tamanho do bucket conforme a densidade real de eventos e ampliar a janela de pico de erros com resolução 10× mais 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

Reconstrói um trace distribuído a partir de múltiplos arquivos de log NDJSON. Dado um trace_id, coleta todos os eventos correlacionados em ordem cronológica em todos os arquivos e expõe os serviços envolvidos e a duração 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

Analisa um arquivo de log para inferir seu formato de wrapper (NDJSON, Syslog, logs de contêiner Kubernetes) e extrair esquemas de tipos, identificando chaves polimórficas, padrões de timestamp e campos de severidade.

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

group_semantic_patterns

Agrupa mensagens de log dinamicamente usando o algoritmo de parsing Drain baseado em árvore de profundidade fixa para isolar templates de log distintos e analisar suas distribuições de parâmetros (variações de curinga).

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 o tailing de logs em segundo plano com alertas de anomalia em tempo real por Z-score em picos de frequência de erros e limites de proteção de memória heap. Envia notificações diretamente por canais JSON-RPC padrão.

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

Um gateway unificado para consultar provedores centrais de log (Datadog, Splunk, Elasticsearch), convertendo padrões de busca para dialetos específicos de cada fornecedor e mapeando a saída para a estrutura padronizada do Modelo de Dados de Log do OpenTelemetry.

⚡ Configuração

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

🚀 Uso

"Analise /var/log/app.log.ndjson — resuma a linha do tempo de erros em janelas de 5 minutos, detecte quaisquer picos anômalos e mostre as entradas de erro ao redor do pico."

Funciona muito bem junto com:

📦 Links

Licença

MIT