4.8 KiB
Guia de Integração Langfuse
Este guia descreve como o Langfuse está integrado ao assistente e como utilizar suas funcionalidades de observabilidade e rastreamento.
Índice
- O que é Langfuse
- Como está integrado
- Credenciais
- Rastreamento automático via LangChain
- Tags por dashboard
- Adicionando scores customizados
- Visualizando traces
O que é Langfuse
Langfuse é uma plataforma de observabilidade para aplicações LLM que permite:
- Rastrear automaticamente todas as chamadas ao modelo (tokens, latência, erros)
- Inspecionar o histórico de mensagens e chamadas de tools
- Adicionar scores e métricas customizadas por trace
- Analisar performance e uso ao longo do tempo
Como está integrado
A integração é feita em dois módulos:
dynamo.py — inicialização do cliente
O cliente Langfuse é instanciado na carga do módulo, usando credenciais obtidas do AWS Secrets Manager:
from langfuse import Langfuse
secrets = json.loads(get_secret())
langfuse = Langfuse(
public_key=secrets["LANGFUSE-PUBLIC-KEY"],
secret_key=secrets["LANGFUSE-SECRET-KEY"],
host=os.environ["LANGFUSE_HOST"],
)
O objeto langfuse é exportado e reutilizado pelo orquestrador.py.
orquestrador.py — rastreamento por execução
A cada chamada ao agente, um CallbackHandler do LangChain é criado e passado na configuração do grafo LangGraph. Isso registra automaticamente no Langfuse todas as etapas da execução — chamadas ao modelo, chamadas de tools e mensagens trocadas.
Ao final da execução, langfuse.flush() garante o envio dos dados pendentes.
from langfuse.langchain import CallbackHandler
from .dynamo import langfuse
langfuse_handler = CallbackHandler()
config = {"callbacks": [langfuse_handler], "tags": [base]}
final_state = agent.invoke(initial_state, config=config)
langfuse.flush()
Credenciais
As chaves do Langfuse são armazenadas no AWS Secrets Manager, no secret definido pela variável de ambiente SECRET_NAME. O secret deve conter as seguintes chaves:
| Chave no secret | Descrição |
|---|---|
LANGFUSE-PUBLIC-KEY |
Chave pública do projeto Langfuse |
LANGFUSE-SECRET-KEY |
Chave secreta do projeto Langfuse |
O endpoint do servidor é configurado pela variável de ambiente LANGFUSE_HOST.
Rastreamento automático via LangChain
O CallbackHandler captura automaticamente, sem código adicional:
- Cada chamada ao modelo Bedrock (input, output, tokens)
- Chamadas às tools
get_monthly_reporteget_consolidated_keys - Sequência de passos do grafo LangGraph
- Erros e exceções durante a execução
Cada invocação de orquestrador.main() gera um trace independente no Langfuse.
Tags por dashboard
A tag base (nome do dashboard, ex: bacio_transacional_loja_app) é passada em cada execução:
config = {"callbacks": [langfuse_handler], "tags": [base]}
Isso permite filtrar traces no Langfuse por cliente/dashboard.
Adicionando scores customizados
Para registrar métricas adicionais em um trace, use a API do cliente langfuse após a execução do agente. O trace ID pode ser obtido via langfuse_handler.get_trace_id().
Tipos de score
| Tipo | Uso |
|---|---|
NUMERIC |
Valores numéricos (ex: satisfação 1–5, tempo de resposta) |
CATEGORICAL |
Valores de categoria (ex: canal de origem, qualidade) |
BOOLEAN |
Verdadeiro/falso |
Exemplo: score após execução
from langfuse.langchain import CallbackHandler
from .dynamo import langfuse
langfuse_handler = CallbackHandler()
config = {"callbacks": [langfuse_handler], "tags": [base]}
final_state = agent.invoke(initial_state, config=config)
trace_id = langfuse_handler.get_trace_id()
if trace_id:
langfuse.score(
trace_id=trace_id,
name="canal_origem",
value="api",
data_type="CATEGORICAL",
)
langfuse.flush()
Sempre chame
langfuse.flush()depois de registrar scores para garantir o envio.
Visualizando traces
Acesse a interface web do Langfuse no endereço configurado em LANGFUSE_HOST.
Navegação útil
| O que ver | Onde ir |
|---|---|
| Todas as execuções | Traces |
| Execuções por dashboard | Traces → filtrar por tag |
| Tokens por modelo | Dashboard → Usage |
| Erros e falhas | Traces → filtrar por status ERROR |
| Scores registrados | Trace individual → aba Scores |