Langfuse — Observabilidade de LLM¶

Plataforma de tracing e observabilidade das aplicações de IA. Os fluxos integrados enviam registros das chamadas de modelo: etapas, tokens, custo e tempo. O conteúdo de entrada e saída depende do mascaramento configurado na aplicação.

O serviço usa Langfuse v3, hospedado em br-sao, e atende os ambientes do BravoCore sob Coolify.

Instância de suporte aos ambientes Coolify¶

Acesse langfuse-2608.bravonix.ia.br e selecione o projeto DEV, HOMOLOG ou PROD, conforme a aplicação investigada.

O Langfuse é compartilhado pelos três ambientes e roda fora do Coolify. O escopo de suporte ao BravoCore documentado aqui é somente o dos ambientes Coolify.

Acesso¶

Recurso	URL
Interface	langfuse-2608.bravonix.ia.br
API pública	`https://<instância>/api/public/...`

Onde estão as credenciais?

Login da interface e as chaves de projeto (usadas pelas aplicações e pela API) ficam com a equipe de desenvolvimento. Solicite acesso ao responsável pelo serviço.

A API pública usa autenticação básica com o par de chaves do projeto:

curl -u "<public_key>:<secret_key>" \
  "https://<instância>/api/public/traces?limit=10"

As aplicações estão configuradas para enviar por HTTPS ao domínio do Langfuse.

O que fica registrado¶

Para cada requisição que envolve um modelo:

Informação	Exemplo do que aparece
Prompt e resposta	Conteúdo integral ou substituído por marcadores, conforme o mascaramento
Árvore de execução	Nós do LangGraph percorridos, ferramentas chamadas, ordem e aninhamento
Consumo	Tokens de entrada e saída, custo calculado por modelo
Desempenho	Latência de cada etapa e do total
Identificação	Usuário, sessão/conversa e tags de contexto (ex.: `surface:chat`, `mode:auto`)
Erros	Exceções e respostas de erro do provedor, com o payload que as causou

Mascaramento depende do ambiente

Conferido em 10/09/2026 nos ambientes novos do Adapter: LANGFUSE_MASK_PII=True no backend e no worker de PROD; nos backends e workers de DEV e HOMOLOG, está False. Em PROD, o código substitui entrada e saída por marcadores antes do envio. Metadados, como identificadores, tags, tokens e custo, continuam visíveis. Essa proteção não equivale a anonimizar todo o registro.

Configuração do backend e dos workers¶

O backend atende as requisições; o worker executa as análises em segundo plano. No Coolify, cada recurso tem suas próprias variáveis. Configurar somente o backend não configura o worker.

Em cada processo que executa chamadas de IA, conferir:

Variável	Finalidade
`LANGFUSE_HOST`	Endereço da instalação correta
`LANGFUSE_PUBLIC_KEY` e `LANGFUSE_SECRET_KEY`	Par de chaves do projeto correspondente ao ambiente
`LANGFUSE_ENABLED`	Deve estar `True` para enviar registros
`LANGFUSE_MASK_PII`	Deve permanecer `True` em PROD para proteger entrada e saída

Após alterar as variáveis, redeployar o recurso e conferir os valores efetivos no novo container, sem imprimir as chaves.

Correção verificada em 10/09/2026: o worker de PROD estava sem essas configurações e com o envio desligado. A configuração foi aplicada, mantendo o mascaramento e a mesma versão do código. Um registro sintético enviado de dentro do novo container chegou ao projeto PROD. Uma análise real posterior ainda precisa confirmar o fluxo completo. Registros antigos não são enviados automaticamente.

Para validar: abrir o projeto DEV, HOMOLOG ou PROD → Tracing, conferir período e filtros e executar um fluxo integrado. Um teste sintético comprova conexão e ingestão; não comprova que todos os fluxos da aplicação enviam registros. Em 10/09/2026, antes dos testes, DEV não tinha execuções reais de agentes no banco e a última registrada em HOMOLOG era de 11/08.

Para que usar¶

Depurar um agente: ver exatamente qual prompt foi montado, que contexto o RAG injetou e por que a resposta saiu daquele jeito
Investigar lentidão: identificar a etapa que consumiu o tempo (busca vetorial, reranking, geração)
Acompanhar consumo: tokens e custo por agente, por usuário ou por período
Rastrear erro em produção: partir do erro do usuário até o payload exato que o provocou

Arquitetura¶

flowchart LR
    subgraph APP["Aplicação observada"]
        A["BravoCore no Coolify<br>API + worker do ambiente"]
    end

    subgraph LF["Langfuse (self-hosted)"]
        B["Web (UI + API)"]
        C["Worker<br>processa a fila de ingestão"]
        D[("ClickHouse<br>traces e observações")]
        E[("PostgreSQL<br>projetos, usuários, config")]
        F[("Redis<br>fila de ingestão")]
        G[("MinIO<br>payloads grandes")]
    end

    A -->|"traces"| B
    B --> F
    F --> C
    C --> D
    C --> G
    B --> D
    B --> E
    B --> G

Componente	Papel
Web	Interface e API pública do Langfuse
Worker	Consome a fila e grava os traces no armazenamento analítico
ClickHouse	Traces e observações (volume alto, consulta analítica)
PostgreSQL	Metadados: organizações, projetos, usuários, configuração
Redis	Fila de ingestão dos eventos
MinIO	Payloads grandes (prompts e respostas extensos)

O Langfuse roda em infraestrutura separada dos ambientes do Adapter, em br-sao (São Paulo). Um deploy do BravoCore não recria o serviço de observabilidade.

Comportamento¶

Ingestão assíncrona: o trace aparece na UI alguns segundos após a requisição terminar; a aplicação não espera pelo Langfuse
Falha isolada: se o Langfuse cair, a aplicação continua respondendo — o envio de traces é best-effort
Retenção: sem expiração configurada; os traces ficam armazenados indefinidamente
Desligável: o BravoCore tem uma chave de configuração que transforma o tracing em no-op, sem alterar código

Troubleshooting¶

Sintoma	Causa provável	Ação
Trace não aparece na UI	Filtros, ingestão pendente ou worker do Langfuse fora do ar	Conferir período e filtros; depois verificar a ingestão do Langfuse
Teste do backend aparece, mas análises em segundo plano não	Worker da aplicação sem configuração própria	Conferir as cinco variáveis no worker que executa a análise e redeployá-lo
Projeto vazio sem erro	Não houve execução integrada nesse ambiente	Conferir uso real; apenas abrir a aplicação não gera chamadas de modelo
Nenhum trace de nenhuma aplicação	Tracing desligado, chaves de projeto trocadas — ou instância errada aberta	Conferir o endereço documentado, o tracing da aplicação e o projeto DEV, HOMOLOG ou PROD
Trace sem tokens nem custo	Modelo sem preço cadastrado, ou provedor não devolveu os metadados de uso	Cadastrar o custo do modelo no projeto
UI lenta em consultas longas	Consulta analítica sobre janela ampla no ClickHouse	Reduzir o período ou filtrar por projeto/tag