LLM Observability

Rastreia cada uso de modelo de linguagem como um trace no Langfuse: o passo comum vira span, a chamada ao modelo vira generation com modelo, parâmetros, tokens e a versão do prompt que a gerou, e a qualidade da resposta vira um score preso ao trace. O prompt fica no Langfuse, versionado e lido por label. Com isso, “o modelo piorou” deixa de ser adivinhação: dá para ver qual versão do prompt, qual entrada e qual resposta.

passos: 6
arquivos: 10
testes: 0
tecnologias: 10

Infraestrutura realTypeScriptBunElysiaPostgreSQLRedisMinIOClickHouseOpenTelemetryLangfuseDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um banco usa um LLM para triar PIX suspeitos: ele lê os sinais da conta e devolve risco e ação. Cada triagem vira um trace com a conta como userId e o PIX como sessionId. Quando o modelo responde algo que o sistema não trata ("risk": "elevated", "action": "block"), o score de contrato do trace fica 0 — é esse score que aponta a regressão depois de uma troca de prompt ou de modelo. O CPF do pagador e a chave PIX nunca chegam ao Langfuse.

Planta

Sequência

7/7

7 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Prompt, custo e latência de LLM.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

instrumentation.ts+2

01
instrumentation.ts sobe o OpenTelemetry com o LangfuseSpanProcessor, cujo mask substitui CPF, e-mail, telefone e cartão em tudo que é exportado
02
promptProduction lê o prompt pelo label production, com cache de 60 s e fallback local — o Langfuse fora do ar não trava a triagem
03
transferTriage abre o trace dentro de propagateAttributes (conta, PIX, tags): todas as observações herdam esses atributos
04
A busca de sinais é um span; a chamada ao modelo é uma generation com modelo, parâmetros, tokens e { name, version, isFallback } do prompt
05
verdictIsWellFormed define o score: 1 se a resposta é JSON com risco e ação do contrato, 0 em qualquer outro caso
06
Telemetria é best-effortFlush e shutdown com prazo; falha de exportação custa o trace, nunca a decisão

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Cada resposta do modelo é explicável: entrada, prompt, tokens, score
Prompt versionado e por label: rollback sem deploy
Score automático aponta regressão antes do cliente
Máscara no processor cobre tudo que sai

Custos

Uma stack de seis serviços para operar, ou um custo de SaaS
O prompt deixa de estar no repositório e na revisão de código
O score só mede o que o contrato define; qualidade exige avaliação humana ou por modelo
Padrões de PII precisam acompanhar novos formatos de dado

apps/observability/llm-observability

10 arquivos

src/

instrumentation.tsSDK OTel com o processor do Langfuse, máscara de PII e flush com prazo
triage_fraud.tsTrace da triagem: atributos propagados, span, generation e score
prompt_fraud.tsPrompt versionado no Langfuse: seed idempotente, leitura por label com cache e fallback
verdict_contract.tsContrato do veredito e a regra do score
pii_mask.tsMáscara de CPF, e-mail, telefone e cartão
services_stub.tsServiço de sinais e gateway do modelo (substituto do provedor, com uso de tokens)
langfuse_read.tsLeitura do trace pela API pública do Langfuse
config_llm.tsConfiguração validada do ambiente
demo.tsdemoTrês PIX triados e cada trace lido de volta do Langfuse

docker-compose.ymlinfraLangfuse auto-hospedado, já provisionado com projeto e chaves

Executar · com Docker

$ docker compose up -d --wait# sobe PostgreSQL · Redis · MinIO · ClickHouse · Langfuse
$ cp .env.example .env# variáveis de ambiente
$ bun install# dependências
$ bun run demo# roda o cenário
$ bun run test# integração contra o serviço real
$

A stack do Langfuse (web, worker, PostgreSQL, ClickHouse, Redis, MinIO) roda as migrações no primeiro boot. UI em http://localhost:3000 — dev@local.test / local-dev-password.

Requisitos: BunDocker
Sobe junto: PostgreSQLRedisMinIOClickHouseLangfuse

Relações

Onde ele se encaixa

Mapa

LLM Observability

Combina com4

Por que se relacionam

Combina com

Teste rápido

Qual destes combina com LLM Observability?

Próximo projeto · Observabilidade & OperaçõesSigNoz — Observabilidade OpenTelemetry-nativa

Contatos

LLM Observability