Helios: Transformando Telemetria SigNoz em um Agente de IA em Chamada

Após um deploy, a pergunta raramente é “temos dashboards?” — é “o que realmente quebrou e o que devemos fazer?” Helios é nossa resposta: um agente de IA que trata o SigNoz como a fonte da verdade, consulta-o através do SigNoz MCP e responde como um engenheiro de plantão afiado.

Este post passa pelo que construímos para o hackathon Agents of SigNoz, como OpenTelemetry e SigNoz se encaixam e os desafios que enfrentamos ao conectar um LLM a rastros reais.

O que é Helios

Helios é um CLI + API HTTP opcional que executa tarefas de observabilidade:

Por trás das câmeras, é um loop de agente padrão: LLM ↔ ferramentas ↔ JSON validado. As ferramentas não são raspadores desenvolvidos internamente — são ferramentas SigNoz MCP apontadas para uma pilha local SigNoz CE.

Por que SigNoz

Precisávamos de três coisas:

1. Ingestão nativa do OpenTelemetry — aplicativos de demonstração já falam OTLP.
2. APIs consultáveis para um agente — MCP expõe lista/busca/agregação sem reinventar o SQL do ClickHouse.
3. Uma interface que humanos confiam — cada resposta do Helios pode ter um link direto para os mesmos rastros que um engenheiro abre no SigNoz.

O SigNoz CE auto-hospedado (Docker Compose via Foundry/casting) nos deu uma interface em :8080, OTLP em :4317/:4318 e MCP em :8000/mcp sem dependência de SaaS para a demonstração.

Arquitetura (breve)

  loadgen ──► checkout ──► payment ──► inventory     
                    │ OTLP
                    ▼
            otel-collector (kind: observability)
                    │ OTLP → host gateway :4317
                    ▼
         ┌──────────────────────────┐
         │  SigNoz CE (Docker)      │
         │  UI :8080 · OTLP · CH    │
         │  MCP :8000/mcp           │
         └────────────▲─────────────┘
                      │ MCP tools
         ┌────────────┴─────────────┐
         │  Helios (CLI / :9090)    │
         │  LLM + agent loop        │
         └──────────────────────────┘

Papéis do pipeline

• Aplicativos — Serviços FastAPI instrumentados com OpenTelemetry (FastAPI + instrumentação automática httpx).
• Coletor — Agrupa rastros/métricas/logs e exporta para SigNoz.
• SigNoz — Armazena telemetria; interface para humanos; MCP para o agente.
• Helios — Planeja investigações, chama ferramentas MCP, emite resultados estruturados.

Como emitimos telemetria no SigNoz

Cada serviço de demonstração configura um provedor de rastreador e exportador gRPC OTLP em direção ao coletor em cluster:

endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://otel-collector:4317")
resource = Resource.create({"service.name": service_name, ...})
provider = TracerProvider(resource=resource)
exporter = OTLPSpanExporter(endpoint=endpoint, insecure=True)
provider.add_span_processor(BatchSpanProcessor(exporter))
FastAPIInstrumentor.instrument_app(app)
HTTPXClientInstrumentor().instrument()

Falhas são injetadas como variáveis de ambiente de Deployment (ERROR_RATE, BASE_LATENCY_MS, FAIL_DOWNSTREAM, CPU_BURN_MS) para que possamos reproduzir cenários: linha de base saudável, erros elevados no checkout, timeouts de pagamento→inventário e pressão de carga.

Desafio que enfrentamos: No Docker Desktop + kind, host.docker.internal para o coletor → SigNoz preferiu IPv6 e quebrou o gRPC. Fixar o exportador para o IPv4 do gateway do host (192.168.65.254:4317) resolveu “rastros ausentes no ClickHouse.”

Como o Helios lê o SigNoz (MCP)

Helios se conecta a http://localhost:8000/mcp, lista ferramentas (~40 em nossa demonstração) e permite que o modelo as chame. O playbook é deliberado:

1. signoz_list_services — confirmar que o serviço existe na janela.
2. signoz_aggregate_traces — count / p95 com aggregateOn=duration_nano, além de error: true para falhas.
3. signoz_search_traces — amostrar spans de erro.
4. signoz_get_trace_details — quando RCA precisa da história de pagamento→inventário.

A configuração de casting local habilita MCP e impersonação, de modo que o agente não precise de uma chave de API do cliente; o servidor MCP mantém uma credencial do lado do servidor.

Exemplo de investigação livre:

helios --quiet investigate \
  "Por que o pagamento está com timeout? O inventário é a dependência que falha?" \
  --service payment-service \
  --service inventory-service \
  --namespace demo \
  --start "$START" --end "$END"

Resposta típica (parafraseada de uma execução real): o pagamento está com timeout porque a latência p95 do inventário está em torno de ~3s; o pagamento vê ReadTimeout / HTTP 504 — o inventário é a dependência que falha, mesmo quando não emite spans de erro próprios.

Essa distinção — dependência lenta vs dependência com erro — só aparece claramente quando o agente pode unir rastros entre serviços no SigNoz.

Cenários de demonstração que validamos contra o SigNoz