🌐 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
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:
- Ingere e Sanitiza: Mascara dados sensíveis (LGPD / GDPR), preservando a topologia de redes privadas RFC 1918 para diagnóstico de pods.
- Investiga em Paralelo: Aciona agentes especialistas para correlacionar logs (Elastic/LogHub), inspecionar infraestrutura (Postgres, Redis, K8s) e consultar manuais de crise (RAG Híbrido).
- Gera Mitigação Segura com HITL: Formula planos de remediação auditáveis com diffs de código e estratégia de rollback.
- 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.
- Compila Post-Mortem: Gera relatórios estruturados e PDFs auditáveis com hash criptográfico SHA-256.
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.
- 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.
Embora Datadog e Sentry sejam brilhantes em alertar, a jornada de resolução tradicional ainda possui um grande gargalo humano:
-
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.
-
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 │
└─────────────────────────────────────────┘ └──────────────────────────────────────────────┘
| 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 |
| 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 |
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 }
}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 pgbouncerO 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).
Após a mitigação, o sistema gera o Post-Mortem oficial com hash SHA-256 e download imediato em PDF.
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
-
Stack: Python 3.12 + FastAPI + Pydantic v2 + instrumentação nativa oficial
dd-trace-pydo 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.
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:
- 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 - Consulta Remota à Branch Principal: O
LogTraceAnalystAgentdo 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. - 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.
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.
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 | ❌ 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 | ❌ Sem HITL | ✅ Hash SHA-256 em PDF | |
| Independência de Provedor (Agnóstico) | ❌ Walled Garden | ❌ Não aplicável | ✅ Universal Tool Gateway |
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"]
| 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. |
- Checkout Schema Mismatch: Coluna ausente após deploy em microsserviço -> Hotfix SQL ou rollback.
- PostgreSQL Connection Pool: Queries ociosas travando conexões (
CPU 95%) ->pg_terminate_backend()seguro. - Payment Gateway Latency: Timeout externo p99 > 15s -> Ativação de circuit breaker e rota de contingência.
- Model Drift Crítico: Queda súbita de 52% na conversão -> Rollback do deployment de inferência.
- Python 3.12+
- Gerenciador UV instalado (
pip install uvoucargo install uv)
# 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# 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)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).