Como observar a Hub API em produção — BI no admin, traces em Langfuse, erros em GlitchTip e alertas operacionais.

Observabilidade

A Hub API é observada por quatro pilares complementares: métricas de negócio (BI), traces de LLM, erros de aplicação e alertas de infraestrutura. Esta página descreve onde cada sinal vive, como acessá-lo e quando consultá-lo durante incidentes ou análises de produto.

A base é o stack LGTM (Loki, Grafana, Tempo, Prometheus) hospedado em infra-1, complementado por GlitchTip para erros e Langfuse para traces de agentes LangGraph. Para correlacionar erro → trace → log em uma chamada, use a ferramenta obs.correlate_issue exposta pelo MCP simplafy-admin.

Visão geral dos 4 pilares

A Hub API participa de quatro fontes de telemetria, cada uma com responsabilidade distinta:

Pilar	Stack	Endpoint	O que responde
Métricas de negócio (BI)	Postgres + endpoints `bi_*` no admin MCP	`simplafy-admin` MCP tools	KPIs, uso por usuário, índice de adoção
Métricas técnicas	Prometheus + Grafana	`grafana.simplafy.com.br`	CPU, memória, restarts, latência de pod
Traces (LLM e HTTP)	Grafana Tempo + Langfuse	`otel.simplafy.com.br`, `langfuse.simplafy.com.br`	Execução de agentes, tool calls, latência
Erros de aplicação	GlitchTip	`glitchtip.simplafy.com.br`	Exceções, stack traces, taxa de erro
Logs	Loki + Promtail	via Grafana	Logs estruturados de pods e proxies

Os quatro pilares são coletados em 4 clusters K8s e 3 BR-Proxies. A Hub API roda no namespace simplafy-prd-hub no cluster prd-2 e expõe métricas pelo deployment simplafy-hub-api.

BI no admin

As métricas de negócio do Hub são expostas pelo MCP simplafy-admin via ferramentas prefixadas com bi_. Elas consultam o Postgres do Hub (simplafy-personalized namespace, pod postgres-*) e retornam KPIs agregados por organização, usuário e janela temporal.

Ferramentas disponíveis:

bi_get_kpis          # KPIs agregados por organização e janela
bi_get_metrics       # séries temporais de métricas de uso
bi_get_usage_index   # índice de adoção composto
bi_get_users         # lista usuários com métricas resumidas
bi_get_user_detail   # detalhamento de um usuário específico

Use estas ferramentas para responder perguntas como "qual organização mais executa agentes esta semana?" ou "qual a curva de adoção desde o onboarding?". O acesso é via MCP — não há endpoint REST público para BI na Hub API.

BI lê o Postgres de produção em modo somente leitura. Para análises pesadas ou janelas grandes, prefira bi_get_metrics com filtros explícitos de período em vez de varreduras completas.

Traces em Langfuse

Toda execução de agente LangGraph é traceada no Langfuse (langfuse.simplafy.com.br, hospedado em infra-2). O tracing é wired no compile do grafo em oap_agent/agent.py — cada turno de conversa produz um trace com:

Inputs e outputs do agente
Chamadas a tools MCP com latência e payload
Prompts resolvidos a partir do Langfuse Prompt Management
Custos e tokens por modelo

A Hub API se conecta a traces indiretamente: quando uma requisição HTTP dispara um agente (ex.: rota de chat), o trace_id é propagado e fica disponível no Langfuse. Para traces puramente HTTP (sem LLM), o OTel Collector em otel.simplafy.com.br envia spans para o Tempo, visualizáveis no Grafana.

Buscar um trace

Abra langfuse.simplafy.com.br e selecione o projeto correspondente à organização.

Filtre por session_id, user_id ou intervalo de tempo. Sessões correspondem a threads de conversa.

Inspecione o trace: cada nó do grafo aparece como span; tools MCP aparecem como spans aninhados com input/output completos.

Convenção de naming de prompts e label scheme: veja docs/langfuse-prompts.md no repositório simplafy-hub.

Erros no GlitchTip

GlitchTip (glitchtip.simplafy.com.br) captura exceções de todos os apps da Hub. A configuração relevante:

9 projetos GlitchTip cobrem web, API, MCP server, RAG, LangGraph e consumer
Webhooks de todos os projetos vão para https://n8n-hub.simplafy.com.br/webhook/glitchtip-events
Um workflow n8n (bzp5JdOOLXhqF4xI) faz triagem com AI e abre issue no GitHub quando aplicável
Formato do webhook é Slack-like (body.attachments[0].title, title_link, fields[]), não Sentry

Consultar issues via CLI

bash .claude/skills/glitchtip/glitchtip issues --project simplafy-hub-api
bash .claude/skills/glitchtip/glitchtip issue <id>

Consultar via MCP

// correlaciona issue + trace + logs em uma chamada
await obs_correlate_issue({ issue_id: "SIMPLAFY-HUB-LANGGRAPH-2P" });

Durante janelas de deploy, é normal ver picos de Error: aborted no GlitchTip — são ECONNRESET transientes do rolling update. Só investigue se persistir fora do deploy.

Alertas e SLAs

Alertas de infraestrutura são definidos no Prometheus/Alertmanager e enviam para Brevo SMTP. As regras ativas que impactam a Hub API:

Regra	Condição	Janela
CrashLoopBackOff	Pod em loop de restart	2min
OOMKilled	Pod morto por OOM	0s (imediato)
Pod restarts	Mais de 5 restarts por hora	5min
Memory >90%	Uso de memória do pod	5min
Disk >85%	Uso de disco do nó	5min
PVC >90%	Uso de volume persistente	5min

Há 18 alert rules no GlitchTip e 15 uptime monitors cobrindo URLs públicas (hub.simplafy.com.br/api/v1/* entre elas). O dashboard principal no Grafana é "Simplafy Infraestrutura" (v52).

Onde olhar primeiro em um incidente

Confira grafana.simplafy.com.br — gauges dos 9 servidores e timeseries do cluster prd-2.

Em glitchtip.simplafy.com.br, filtre o projeto simplafy-hub-api para ver se há issue ativa nos últimos minutos.

Pegue o trace_id do erro (campo trace_id ou langfuse_session_id no contexto) e abra no Langfuse ou Tempo.

Use obs.correlate_issue no MCP simplafy-admin para juntar erro + trace + logs em uma resposta.

Observabilidade

GlitchTip

Grafana

Langfuse

On this page