Phase 19 - Lesson 11

Capstone 11 — Painel de Observabilidade & Avaliação de LLM

O Langfuse tornou-se open-core. O Arize Phoenix publicou os mapeamentos semânticos GenAI de 2026. A Helicone e a Braintrust dobraram a aposta na atribuição de custo por usuário. O OpenLLMetry da Traceloop tornou-se a instrumentação SDK de fato. O formato de produção consiste no ClickHouse para rastreamentos (traces), Postgres para metadados, Next.js para a interface de usuário (UI) e um pequeno exército de trabalhos de avaliação (DeepEval, RAGAS, LLM-judge) rodando sobre rastreamentos amostrados. Desenvolva um painel auto-hospedado (self-hosted), consuma dados de pelo menos quatro famílias de SDK e demonstre a detecção de uma regressão injetada em menos de cinco minutos.

Type: Capstone Languages: TypeScript (UI), Python / TypeScript (ingestion + evals), SQL (ClickHouse) Prerequisites: Phase 11 (LLM engineering), Phase 13 (tools), Phase 17 (infrastructure), Phase 18 (safety) Phases exercised: P11 · P13 · P17 · P18 Time: 25 horas

Problem

Toda equipe de IA rodando tráfego de produção em 2026 mantém um plano de observabilidade junto ao modelo. Atribuição de custo. Detecção de alucinações. Monitoramento de desvio (drift). Sinais de jailbreak. Painéis de SLO. Alertas de vazamento de PII. As referências de código aberto — Langfuse, Phoenix, OpenLLMetry — convergiram para as convenções semânticas (semantic conventions) GenAI do OpenTelemetry como o esquema de ingestão. Agora você pode instrumentar OpenAI, Anthropic, Google, LangChain, LlamaIndex e vLLM com um único SDK e enviar spans compatíveis.

Você construirá um painel auto-hospedado que ingere dados de pelo menos quatro famílias de SDK, executa um pequeno conjunto de trabalhos de avaliação sobre rastreamentos amostrados, detecta desvios e gera alertas. A meta de medição: dada uma regressão injetada deliberadamente (um prompt que começa a gerar PII), o painel a detecta e dispara um alerta em menos de cinco minutos.

Concept

A ingestão é feita via OTLP HTTP. O SDK produz spans com convenções semânticas de GenAI: gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.response.id, llm.prompts, llm.completions. Os spans vão para o ClickHouse para análise colunar; os metadados (usuários, sessões, aplicativos) vão para o Postgres.

As avaliações rodam como trabalhos em lote (batch jobs) sobre rastreamentos amostrados. O DeepEval avalia fidelidade (faithfulness), toxicidade e relevância da resposta. O RAGAS avalia métricas de recuperação quando o rastreamento carrega contexto de recuperação. LLM-judges personalizados executam verificações específicas do domínio (vazamento de PII, resposta fora da política). As execuções de avaliação gravam de volta no mesmo ClickHouse como spans de avaliação vinculados ao rastreamento pai.

A detecção de desvios monitora distribuições no espaço de embeddings ao longo do tempo (divergência PSI ou KL em embeddings de prompts), além de tendências de pontuação de avaliação. Os alertas alimentam o Prometheus Alertmanager e depois o Slack / PagerDuty. A UI é construída em Next.js 15 com Recharts.

Architecture

aplicações de produção:
  OpenAI SDK  +  Anthropic SDK  +  Google GenAI SDK
  LangChain + LlamaIndex + vLLM
       |
       v
  OpenTelemetry SDK com GenAI semconv
       |
       v  OTLP HTTP
  coletor (ingestão, amostragem, fan-out)
       |
       +-------------+-----------+
       v             v           v
   ClickHouse    Postgres    arquivo S3
   (spans)       (metadados) (eventos brutos)
       |
       +---> jobs de eval (DeepEval, RAGAS, LLM-judge)
       |     amostrados ou todos os traces
       |     grava spans de eval de volta
       |
       +---> detector de desvio (PSI / KL em embeddings de prompt)
       |
       +---> métricas Prometheus -> Alertmanager -> Slack / PagerDuty
       |
       v
   painel Next.js 15 (Recharts)

Stack

Ingestão: OpenTelemetry SDKs + convenções semânticas GenAI; transporte OTLP HTTP
Coletor: OpenTelemetry Collector com processador de amostragem de cauda (tail-sampling) (para controle de custos)
Armazenamento: ClickHouse para spans, Postgres para metadados, S3 para arquivo de eventos brutos
Avaliações: DeepEval, RAGAS 0.2, pacote avaliador Arize Phoenix, LLM-judge personalizado
Desvio (Drift): PSI / KL em embeddings de prompts agrupados (sentence-transformers) semanalmente
Alertas: Prometheus Alertmanager -> Slack / PagerDuty
UI: Next.js 15 App Router + Recharts + server actions
SDKs suportados nativamente: OpenAI, Anthropic, Google GenAI, LangChain, LlamaIndex, vLLM

Build It

Configuração do coletor. OpenTelemetry Collector com o receptor OTLP HTTP, um amostrador de cauda (tail-sampler) que mantém 100% dos rastreamentos com erro e 10% dos bem-sucedidos, e exportadores para o ClickHouse e S3.
Esquema do ClickHouse. Tabela spans com colunas espelhando GenAI semconv: gen_ai_system, gen_ai_request_model, input_tokens, output_tokens, latency_ms, prompt_hash, trace_id, parent_span_id, além de um campo JSON para payloads longos. Adicione índices secundários por user_id e app_id.
Teste de cobertura do SDK. Escreva um pequeno aplicativo cliente usando cada SDK (OpenAI, Anthropic, Google, LangChain, LlamaIndex, vLLM) com auto-instrumentação do OpenLLMetry. Verifique se cada um produz spans GenAI canônicos que chegam ao ClickHouse.
Trabalhos de avaliação (eval). Um trabalho agendado lê os rastreamentos amostrados dos últimos 15 minutos e executa testes do DeepEval para fidelidade, toxicidade e relevância de resposta. Os resultados são spans de avaliação vinculados ao rastreamento pai.
LLM-judge personalizado. Um avaliador de vazamento de PII: dada uma resposta, chame uma LLM guardiã para avaliar a probabilidade de vazamento de PII. Respostas com pontuação alta são direcionadas para uma fila de triagem.
Detecção de desvios. Trabalho semanal que calcula o PSI entre os embeddings de prompts agrupados desta semana e a linha de base das últimas 4 semanas. Se o PSI estiver acima do limite, dispara um alerta.
Painel. Next.js 15 com as páginas: visão geral (spans/seg, custo/usuário, latência p95), rastreamentos (busca + visualização em cascata), avaliações (tendência de fidelidade, toxicidade), desvio (PSI ao longo do tempo), alertas.
Cadeia de alertas. O exportador do Prometheus lê os agregados de pontuação de avaliação e percentis de latência; o Alertmanager encaminha para o Slack no caso de avisos e para o PagerDuty para violações críticas.
Sonda de regressão. Injete um bug: o chatbot avaliado começa a vazar CPFs falsos 1% das vezes. Meça o MTTR: desde o bug implantado até o alerta no Slack.

Use It

$ curl -X POST https://my-otel-collector/v1/traces -d @trace.json
[collector]  accepted 1 trace, 3 spans
[clickhouse] inserted 3 spans (app=chat, user=u_42)
[eval]       DeepEval faithfulness 0.82, toxicity 0.03
[drift]      weekly PSI 0.08 (below 0.2 threshold)
[ui]         live at https://obs.example.com

Ship It

outputs/skill-llm-observability.md é o entregável. Dada uma aplicação de LLM, o painel ingere seus rastreamentos, executa avaliações, alerta sobre desvios e exibe o detalhamento de custo/usuário em Next.js.

Peso	Critério	Como é medido
25	Cobertura do esquema de trace	Número de famílias de SDK que produzem spans GenAI canônicos (meta: 6+)
20	Correção da avaliação	Pontuações do DeepEval / RAGAS versus conjunto rotulado manualmente
20	UX do painel	MTTR na regressão injetada (meta inferior a 5 minutos)
20	Custo / escala	Ingestão contínua a 1k spans/seg sem acúmulo de fila
15	Alertas + detecção de desvios	Cadeia Prometheus/Alertmanager executada de ponta a ponta
100

Exercises

Adicione instrumentação personalizada para o framework Haystack. Verifique se os spans canônicos chegam ao ClickHouse com os atributos gen_ai.* corretos.
Substitua o DeepEval pelos avaliadores do Phoenix nos mesmos rastreamentos. Meça o desvio de pontuação entre os dois motores de avaliação.
Refine o detector de desvios: calcule o PSI por app-id em vez de globalmente. Exiba os históricos de desvio por aplicativo.
Adicione uma página de "impacto no usuário": custo por usuário e taxa de falha por usuário com sparklines.
Crie uma política de amostragem de cauda (tail-sampling) que mantenha 100% dos rastreamentos com toxicidade > 0.5, além de uma amostra estratificada de 10% do restante. Meça o viés de amostragem introduzido.

Key Terms

Termo	O que as pessoas dizem	O que realmente significa
GenAI semconv	"Atributos de LLM do OTel"	Especificação OpenTelemetry de 2025 para atributos de span de LLM (sistema, modelo, tokens)
Tail sampling	"Amostra pós-trace"	O coletor decide manter ou descartar um rastreamento após sua conclusão (permite observar erros)
PSI	"Índice de estabilidade da população"	Métrica de desvio que compara duas distribuições; > 0.2 geralmente sinaliza desvio significativo
LLM-judge	"Avaliação como modelo"	Uma LLM que avalia a saída de outra LLM baseando-se em uma rubrica (fidelidade, toxicidade, PII)
Tail-sampling policy	"Regra de retenção"	Regra que decide quais rastreamentos manter versus descartar; erros + taxa de amostragem
Eval span	"Trace de avaliação vinculado"	Span filho contendo uma pontuação de avaliação vinculada ao span da chamada original da LLM
Cost per user	"Economia unitária"	Custo em dólares atribuído a um `user_id` em uma janela de tempo; métrica-chave de produto