Skip to content
henriquebotelhogomesPublic

About

Autonomous Incident Commander Multi-Agent Platform (LangGraph + Anthropic MCP + OpenAI Tools + PostgreSQL Serverless + HITL + Scalar Docs)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

🚨 OpsMesh — Autonomous Incident Commander

Live Demo Scalar Docs Health 200 OK Python 3.12 LangGraph FastAPI Scale-to-Zero License Apache 2.0

🌐 Ambiente Oficial Online (Google Cloud Run):
🔗 Console SRE & Chaos Studio: https://opsmesh-197215016090.us-central1.run.app
📖 Documentação Interativa de APIs (Scalar): https://opsmesh-197215016090.us-central1.run.app/docs
🩺 Health Check & Telemetria em Tempo Real: https://opsmesh-197215016090.us-central1.run.app/health


📌 Visão Geral

O OpsMesh é um sistema multi-agente autônomo projetado para atuar como Incident Commander (Comandante de Incidentes) de nível Staff SRE em sistemas distribuídos de missão crítica.

Quando alertas críticos disparam (Datadog, Prometheus, Grafana), o OpsMesh:

  1. Ingere e Sanitiza: Mascara dados sensíveis (LGPD / GDPR), preservando a topologia de redes privadas RFC 1918 para diagnóstico de pods.
  2. Investiga em Paralelo: Aciona agentes especialistas para correlacionar logs (Elastic/LogHub), inspecionar infraestrutura (Postgres, Redis, K8s) e consultar manuais de crise (RAG Híbrido).
  3. Gera Mitigação Segura com HITL: Formula planos de remediação auditáveis com diffs de código e estratégia de rollback.
  4. Protege Ações Críticas: Bloqueia execuções destrutivas com Human-in-the-Loop (HITL) persistido no PostgreSQL Serverless até a assinatura do engenheiro de plantão.
  5. Compila Post-Mortem: Gera relatórios estruturados e PDFs auditáveis com hash criptográfico SHA-256.

🤝 A Relação com Datadog & Sentry: Uma Parceria Indispensável

Important

O OpsMesh depende 100% do Datadog e do Sentry. Sem eles, o OpsMesh não existiria e seria completamente inviável. O OpsMesh não foi concebido para competir ou substituir essas plataformas consagradas, mas sim para ser a próxima camada de inteligência e ação construída diretamente sobre elas.

🌟 Por que Datadog e Sentry são insubstituíveis?

  • Datadog: É o líder absoluto e padrão global em observabilidade de infraestrutura, APM (Application Performance Monitoring), métricas de saturação de hardware, redes distribuídas e agregação de logs em escala petabyte.
  • Sentry: É o padrão de ouro indiscutível da indústria em rastreamento cirúrgico de exceptions de código, breadcrumbs de contexto, profiling e identificação exata de falhas em aplicações modernas.

Essas duas ferramentas são os olhos, ouvidos e o sistema nervoso sensorial da engenharia moderna. Sem elas, nenhuma equipe de tecnologia sabe com precisão o que está quebrado em produção. O OpsMesh reconhece isso e não tenta reinventar a roda da telemetria: ele consome o ouro bruto que Datadog e Sentry já extraem e agrega o próximo passo de engenharia.


🚀 Onde o OpsMesh vai além? (Da Detecção Passiva à Ação Prescritiva)

Embora Datadog e Sentry sejam brilhantes em alertar, a jornada de resolução tradicional ainda possui um grande gargalo humano:

  1. O Cenário Tradicional (Apenas Datadog & Sentry):

    • O Datadog detecta saturação ou o Sentry captura uma exception crítica.
    • Um alerta toca no PagerDuty às 03:00 da madrugada.
    • O engenheiro SRE humano acorda no susto. Ele precisa abrir 5 abas no navegador, garimpar runbooks desatualizados na wiki, correlacionar logs manualmente, abrir o terminal SSH/Kubectl e tentar adivinhar o comando correto para mitigar a crise sem derrubar outros serviços.
    • MTTR (Tempo Médio de Resolução): 45 a 120 minutos de estresse e prejuízo.
  2. O Cenário com OpsMesh (Datadog/Sentry + Inteligência Prescritiva com HITL):

    • O Datadog/Sentry dispara um webhook para o OpsMesh com a telemetria e o payload do erro.
    • O OpsMesh assume como Comandante de Crise:
      • Sanitiza dados sensíveis (LGPD/GDPR) mantendo IPs de pods intactos.
      • Aciona agentes especialistas de IA para cruzar logs e infraestrutura em segundos.
      • Consulta os manuais oficiais da empresa (SOPs/Runbooks) via RAG Híbrido.
      • Entrega a solução cirúrgica pronta na tela: diagnóstico da causa raiz comprovada, comandos de correção exatos, diff de configuração e script de rollback.
    • Portão Human-in-the-Loop (HITL): O engenheiro humano não precisa caçar comandos no escuro; ele apenas revisa a análise técnica e clica em "Aprovar Mitigação".
    • O OpsMesh executa a remediação com segurança e gera o relatório Post-Mortem oficial com hash criptográfico em PDF.
    • MTTR (Tempo Médio de Resolução): Reduzido para menos de 3 minutos.
┌─────────────────────────────────────────┐       ┌──────────────────────────────────────────────┐
│       DATADOG / SENTRY / GRAFANA        │  ==>  │                   OPSMESH                    │
│      (Olhos & Ouvidos do Sistema)       │       │         (Cérebro & Braço Prescritivo)        │
│                                         │       │                                              │
│  "Detecta erro 504 no Checkout e        │       │  1. Recebe o alerta e investiga em paralelo  │
│   Pool PostgreSQL em 98% de saturação"  │       │  2. Consulta os Runbooks (SOPs) via RAG      │
│                                         │       │  3. Formula o plano exato de mitigação       │
│  (Alerta gerado com perfeição.          │       │  4. Portão HITL: SRE aprova com 1 clique     │
│   Sem ele, o OpsMesh não saberia da dor)│       │  5. Emite relatório Post-Mortem em PDF       │
└─────────────────────────────────────────┘       └──────────────────────────────────────────────┘

📊 Matriz de Simbiose: Datadog & Sentry + OpsMesh

Capacidade Datadog / Sentry OpsMesh Papel Combinado
Coleta de Métricas & APM ✅ Primário (Líder Mundial) ❌ Depende 100% deles Datadog/Sentry monitoram e geram telemetria contínua
Captura de Exceptions & Traces ✅ Primário (Líder Mundial) ❌ Depende 100% deles Sentry isola stack traces e contexto de código
Detecção de Anomalias & Alarmes ✅ Primário (Líder Mundial) ❌ Consome via Webhook Datadog/Sentry acionam o gatilho da crise
Investigação Multi-Agente Autônoma ❌ Não faz ✅ Primário (LangGraph) OpsMesh investiga causas raízes em paralelo
Consulta Inteligente de Runbooks (RAG) ❌ Não faz ✅ Primário (Qdrant+BM25) OpsMesh encontra o procedimento padrão para a crise
Elaboração de Diff e Comandos de Fix ❌ Não faz ✅ Primário (AI Specialist) OpsMesh escreve o plano cirúrgico e o rollback
Portão de Segurança Human-in-the-Loop ❌ Não faz ✅ Primário (LangGraph HITL) Bloqueia mutações até o aval explícito do SRE
Geração de Post-Mortem em PDF Auditável ❌ Não faz ✅ Primário (ReportLab) OpsMesh emite o laudo final com hash SHA-256

🕹️ Dois Modos de Operação: Demonstração (Chaos Studio) vs. Produção Real

Modo Como Funciona Para Quem Serve Custo
Modo Sandbox / Chaos Studio (Botão "Simular Crise") O OpsMesh utiliza seu emulador interno de telemetria baseado em datasets reais do LogHub. Ele simula o envio de alertas no formato do Datadog/Prometheus sem necessidade de contas pagas ou servidores externos. Recrutadores, Tech Leads, demonstrações de portfólio e testes locais. $0.00 (Zero-Token Replay)
Modo Produção Corporativa (Webhook Universal) O OpsMesh expõe o endpoint POST /api/v1/incidents/webhook. Basta cadastrar essa URL nos Webhooks do seu Datadog, Sentry, Grafana ou PagerDuty. Quando um alerta real dispara, o OpsMesh inicia a investigação automaticamente. Ambientes de staging e produção corporativa em nuvem (GCP, AWS, Azure, K8s). Conforme tokens de LLM configurados

📝 Exemplo Prático de Fluxo (Ponta a Ponta)

1. O Alerta Chega (via Datadog ou Chaos Studio)

POST /api/v1/incidents/webhook
{
  "service": "order-service",
  "severity": "P0_CRITICAL",
  "message": "FATAL: remaining connection slots are reserved on node 10.244.1.15",
  "details": { "active_connections": 98, "max_connections": 100 }
}

2. O OpsMesh Investiga e Formula o Tratamento

A equipe de agentes correlaciona os logs, analisa o tráfego e consulta o manual docs/runbooks/connection_pool.md via RAG Híbrido, gerando o plano cirúrgico:

Ação Proposta: DATABASE_TERMINATE_BACKENDS (Risco Alto)
Comandos Gerados:
  $ SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle in transaction' AND state_change < current_timestamp - INTERVAL '5 minutes';
  $ kubectl rollout restart deployment order-service -n production
Plano de Rollback: kubectl rollout restart deployment pgbouncer

3. Portão Human-in-the-Loop (HITL)

O sistema bloqueia qualquer ação destrutiva e apresenta o diagnóstico completo na interface. O engenheiro revisa a causa raiz e clica em "Aprovar Mitigação" (POST /api/v1/incidents/{id}/resume).

4. Auditoria Criptográfica & Post-Mortem

Após a mitigação, o sistema gera o Post-Mortem oficial com hash SHA-256 e download imediato em PDF.


🧪 Ecossistema Chaos Lab: O Laboratório Vivo de Engenharia do Caos

Para comprovar a robustez e o desacoplamento do OpsMesh em cenários reais de produção corporativa, o ecossistema inclui um projeto companheiro independente: o Chaos Lab (d:\ChaosLab / repositório dedicado).

sequenceDiagram
    autonumber
    actor SRE as SRE / Engenheiro de Plantão
    participant CL as 🧪 Chaos Lab (API E-Commerce)
    participant DD as 📊 Datadog APM & Tracing
    participant OM as 🛡️ OpsMesh (Supervisor + Workers)
    participant GH as 🐙 GitHub REST API (Branch main)

    SRE->>CL: Dispara Injeção de Falha (ex: Pool Exhaustion, 504 Timeout)
    CL->>CL: Falha ocorre em runtime (ex: /checkout trava conexões)
    CL-->>DD: Envia traces distribuídos, métricas de saturação e stack traces (ddtrace)
    DD->>DD: Monitor de Anomalia dispara (Error Rate > 5%, p99 > 2s)
    DD->>OM: Webhook de Incidente com stack trace e metadados
    
    rect rgb(24, 30, 42)
        Note over OM,GH: Diagnóstico Cirúrgico & Inspeção de Código
        OM->>GH: Consulta código-fonte exato do arquivo/linha na branch 'main'
        OM->>OM: Recupera Runbooks de Emergência (RAG Híbrido: Qdrant + BM25)
        OM->>OM: Agentes consolidam Causa Raiz + Plano de Remediação em 2 Níveis
    end

    OM->>SRE: Apresenta diagnóstico, diff de código e pausa no Portão HITL
    SRE->>OM: Assina e aprova via interface do Console SRE
    
    par Nível 1: Mitigação Imediata em Runtime (< 5s)
        OM->>CL: Dispara endpoint de estabilização operacional (POST /operations/mitigate)
        CL-->>DD: Erros cessam, gráfico do Datadog volta para verde (0% de erro)
    and Nível 2: Correção Definitiva via GitOps (Assíncrono)
        OM->>GH: Abre Pull Request formal documentado com o patch no repositório do Chaos Lab
    end
Loading

O que é o Chaos Lab?

  • Stack: Python 3.12 + FastAPI + Pydantic v2 + instrumentação nativa oficial dd-trace-py do Datadog.
  • Painel Interativo de Caos: Interface visual com gatilhos de falhas controladas:
    • 🔴 PostgreSQL Connection Pool Leak: Queries sem fechamento determinístico de conexões.
    • 🔴 Cascade 504 Gateway Timeout: Latência forçada de 15s em chamadas upstream de estoque.
    • 🔴 Memory Leak (OOMKilled): Alocação progressiva de memória RAM em tensores sem coleta de GC.
    • 🔴 Payment Gateway Flapping: Injeção aleatória de HTTP 500 no adquirente de cartões.
    • 🎲 Chaos Roulette: Sorteio estocástico de falhas a cada $N$ minutos para auditoria contínua.

🔬 Inspeção Cirúrgica de Código-Fonte via GitHub REST API

Ao contrário de abordagens simplistas que jogam todo o repositório cegamente em um prompt de LLM (estourando orçamentos de contexto e gerando alucinações), o OpsMesh adota uma estratégia stateless e cirúrgica:

  1. Extração de Coordenadas do Datadog: O Datadog entrega o stack trace detalhado:
    File "/app/services/checkout.py", line 142, in process_order
      conn = db_pool.getconn()
    psycopg2.OperationalError: FATAL: remaining connection slots are reserved
    
  2. Consulta Remota à Branch Principal: O LogTraceAnalystAgent do OpsMesh consulta a GitHub REST API (GET /repos/{owner}/{repo}/contents/{path}?ref=main) para inspecionar exatamente o contexto das linhas 120 a 160 do arquivo ativo em produção.
  3. Triangulação de Evidências: A LLM cruza:
    • O Sintoma: Telemetria, APM e stack trace do Datadog.
    • A Causa no Código: As linhas exatas do arquivo do Chaos Lab na branch main.
    • O Procedimento: O manual corporativo (Runbook Markdown) recuperado via RAG Híbrido.

🛡️ O Padrão Ouro de Remediação em Dois Níveis (Two-Tier Remediation)

Em engenharia de confiabilidade de alta maturidade (Google SRE, Netflix, PagerDuty), existe o princípio inviolável de separar a Mitigação da Crise da Correção Definitiva do Código:

Nível Objetivo Velocidade Mecanismo de Execução Governança
Nível 1: Mitigação Operacional (Runtime) Estancar o sangramento e recuperar o SLA/SLO imediatamente. < 5 segundos Chamada de API operacional protegida no Chaos Lab / Kubernetes (ex: reiniciar conexões, ligar circuit breaker). Portão HITL (Aprovação humana expressa).
Nível 2: Correção Definitiva (GitOps) Eliminar a causa raiz no código-fonte permanentemente. Assíncrono Abertura automática de Pull Request formal no GitHub com o patch de código, testes, justificativa técnica e link do post-mortem. Revisão humana por pares (Code Review) e esteira de CI/CD.

Caution

Anti-Pattern Evitado: O OpsMesh nunca comita alterações de código diretamente na branch main de produção sem validação de testes. Todo patch permanente é submetido como Pull Request para manter a integridade da esteira de CI/CD da empresa.


🏆 Posicionamento de Mercado & Análise Competitiva

O OpsMesh atua na lacuna crítica entre as ferramentas de diagnóstico passivo e os gerenciadores de alertas humanos:

Capacidade Datadog Bits AI PagerDuty Advance Devin / Sweep OpsMesh
Ingestão de Alertas Reais de APM (Datadog/Sentry) ✅ Nativo ✅ Webhook ❌ Não faz ✅ Universal Webhook
Orquestração Multi-Agente (LangGraph) ❌ Monolítico ❌ Roteamento básico ❌ Agente único ✅ Supervisor + Workers
Inspeção Cirúrgica de Código (GitHub API) ❌ Não lê código ❌ Não lê código ✅ Lê o repositório ✅ Stateless via Stack Trace
Mitigação em Runtime Nível 1 (< 5s) ❌ Não executa ⚠️ Via Rundeck externo ❌ Não executa ✅ Nativo pós-HITL
Criação de Pull Request Nível 2 (GitOps) ❌ Não faz ❌ Não faz ✅ Abre PR ✅ Nativo pós-HITL
Portão HITL Não-Repudiável (Hash SHA-256) ❌ Sem auditoria ⚠️ Apenas log de chat ❌ Sem HITL ✅ Hash SHA-256 em PDF
Independência de Provedor (Agnóstico) ❌ Walled Garden ⚠️ Parcial ❌ Não aplicável ✅ Universal Tool Gateway

🏛️ Topologia Arquitetural

graph TD
    Alert["Webhook: POST /api/v1/incidents/webhook"] --> PII["PII Sanitizer Middleware<br/>Mascara PII Pública, Preserva RFC 1918"]
    PII --> GuardrailCheck{"Token Budget & Circuit Breaker?"}
    
    GuardrailCheck -->|Cota Excedida| Http429["HTTP 429: Cota Diária Atingida<br/>Convite para BYOK ou Docker Local"]
    GuardrailCheck -->|Autorizado / BYOK| Supervisor["Supervisor: Incident Commander<br/>LangGraph with_structured_output"]
    
    subgraph ToolGateway [Universal Tool Gateway: MCP + OpenAI Tools]
        Adapter["Protocol Adapter & Dispatcher"]
        MCP_Server["Servidores MCP: Anthropic stdio/SSE"]
        OpenAI_Tools["OpenAI Function Calling: DeepSeek / GPT"]
        Adapter <--> MCP_Server
        Adapter <--> OpenAI_Tools
    end
    
    subgraph AgentMesh [Equipe de Agentes Especialistas - LangGraph]
        Supervisor -->|Diagnóstico de Logs| LogAgent["LogTraceAnalystAgent"]
        Supervisor -->|Análise de Infra| InfraAgent["DatabaseInfraAgent"]
        Supervisor -->|Manuais de Crise| RAGAgent["RunbookKnowledgeAgent"]
        
        LogAgent <--> ToolGateway
        InfraAgent <--> ToolGateway
        
        LogAgent --> Synthesis["Nó de Síntese"]
        InfraAgent --> Synthesis
        RAGAgent --> Synthesis
    end
    
    Synthesis --> RemediationPlan["RemediationEngineerAgent:<br/>Geração do Plano & Diff"]
    
    RemediationPlan --> HITL_Gate{"HITL Gate: Ação Crítica?"}
    HITL_Gate -->|interrupt_before| PausedState[("LangGraph Checkpointer:<br/>PostgreSQL Serverless")]
    
    PausedState --> SRE_Notification(["Engenheiro Humano de Plantão<br/>Notificação com Diff"])
    
    SRE_Notification -->|Aprovar| ResumeEndpoint["POST /api/v1/incidents/:id/resume"]
    ResumeEndpoint --> Execution["Execução Segura da Ação"]
    Execution --> PostMortem["AuditPostMortemAgent: Relatório Estruturado & PDF"]
Loading

⚡ Diferenciais de Engenharia

Pilar Detalhes Técnicos
Decision Models Especializados Roteamento e convergência do Supervisor via Jev (typesafe/jev-latest no OpenRouter) com latência sub-30ms, $0.00 de custo de saída e primitivas nativas (Choice, Noul).
Universal Tool Gateway Suporta simultaneamente Anthropic MCP (stdio/SSE) e OpenAI Function Calling (DeepSeek V3/R1, GPT-4o, Llama 3 via Ollama/vLLM).
OpenRouter & Frota Free Gateway integrado com acesso à frota oficial de modelos gratuitos (openrouter/free, nvidia/nemotron-3-ultra-550b-a55b:free, poolside/laguna-s-2.1:free, cohere/north-mini-code:free) com cotas ampliadas por saldo mantido > $10 e suporte BYOK (X-OpenRouter-API-Key).
Datadog Pro APM & Tracing Tracing distribuído ponta a ponta (ddtrace) com propagação de contexto (traceparent), correlacionando falhas do Chaos Lab e nós do LangGraph no OpsMesh.
FinOps & Scale-to-Zero Elegível para Google Cloud Run e Azure Container Apps com min_instances = 0 ($0/mês ocioso).
Armazenamento Zero-Daemon Suporte a LanceDB (vetores serverless em disco, $0 de infra) e DuckDB + Parquet para auditoria e queries analíticas OLAP de MTTR histórico.
Red-Teaming Gate (Promptfoo) Pentest automatizado no CI/CD contra jailbreak, injeção de prompt e tentativa de desvio do portão HITL antes do deploy.
Blindagem Anti-DoW Disjuntor diário de gastos ($1.00/dia), Rate Limiting por IP, padrão BYOK (X-OpenAI-API-Key, X-DeepSeek-API-Key) e Modo Replay Zero-Token.
Observabilidade de LLMs Tracing nativo do LangGraph com LangSmith e suporte a Langfuse (self-hosted).
Quality Gate com Ragas Avaliação contínua no CI/CD com LLM-as-a-Judge: Faithfulness $\ge 0.85$ e Answer Relevancy $\ge 0.80$.
API Moderna com Scalar Documentação interativa e cliente HTTP embutido em /docs e /scalar (Swagger UI descontinuado).
Documentação Tri-língue Portal MkDocs Material com seletor de idiomas: Português (padrão), Inglês e Espanhol.

🧪 Chaos Studio: 4 Cenários Canônicos

  1. Checkout Schema Mismatch: Coluna ausente após deploy em microsserviço -> Hotfix SQL ou rollback.
  2. PostgreSQL Connection Pool: Queries ociosas travando conexões (CPU 95%) -> pg_terminate_backend() seguro.
  3. Payment Gateway Latency: Timeout externo p99 > 15s -> Ativação de circuit breaker e rota de contingência.
  4. Model Drift Crítico: Queda súbita de 52% na conversão -> Rollback do deployment de inferência.

🚀 Quickstart

Pré-requisitos

  • Python 3.12+
  • Gerenciador UV instalado (pip install uv ou cargo install uv)

Instalação

# 1. Clonar o repositório
git clone https://github.com/OpsMesh/OpsMesh.git
cd OpsMesh

# 2. Sincronizar o ambiente virtual com uv
uv sync

# 3. Configurar variáveis de ambiente
cp .env.example .env

# 4. Ativar os hooks de pre-commit
uv run pre-commit install

Executando a API e a Documentação Viva

# Iniciar a API com Scalar Docs
uv run uvicorn src.opsmesh.api.app:app --reload --port 8000

# Acessar a documentação viva da API:
# 👉 http://localhost:8000/docs ou http://localhost:8000/scalar

# Iniciar o portal de documentação MkDocs com i18n
uv run mkdocs serve --dev-addr 127.0.0.1:8080
# 👉 http://localhost:8080 (Português, Inglês e Espanhol)

📚 Base Documental Viva

  • PRD.md: Product Requirements Document (Personas, SLAs, Casos de Uso, NFRs).
  • PROJECT_SPEC.md: Especificação técnica e topologia do sistema.
  • AGENTS.md: Contratos dos agentes, schemas Pydantic v2 e system prompts.
  • TASK.md: Backlog granular de tarefas em checklist por fases de engenharia.
  • .pre-commit-config.yaml: Hooks de qualidade (Ruff, Mypy, Gitleaks, Prettier).

About

Autonomous Incident Commander Multi-Agent Platform (LangGraph + Anthropic MCP + OpenAI Tools + PostgreSQL Serverless + HITL + Scalar Docs)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages