Langfuse Self-Hosted em VPS Docker: Observabilidade, Custos de Tokens e Tracing para Agentes de IA e LLMs

1. O Desafio da 'Caixa-Preta' em Agentes de IA e Cadeias LLM Complexas

Diferente de microsserviços REST tradicionais onde uma requisição segue um caminho de código determinístico, uma aplicação moderna com agentes de IA introduz um nível inédito de não-determinismo:

• Um agente pode decidir acionar 3 ferramentas sequenciais, retroceder em ciclo após receber um erro de validação e realizar 5 chamadas adicionais de modelo antes de responder ao cliente final.
• Se o cliente no WhatsApp receber uma mensagem desconexa ou se o robô travar em silêncio, inspecionar um arquivo de texto com centenas de linhas de log desordenadas não permite identificar em qual nó do raciocínio a alucinação começou.
• Sem telemetria granular de tokens, pequenos ajustes de prompt podem fazer o consumo de tokens de entrada explodir 10 vezes sem que a equipe técnica perceba, resultando em surpresas financeiras desagradáveis no fim do mês.

O Langfuse soluciona esse problema decompondo cada interação em três níveis hierárquicos de observabilidade:

1. Traces: O fluxo completo de uma requisição ponta a ponta (por exemplo, todo o atendimento de um chamado de suporte desde a mensagem inicial do cliente até a resolução).
2. Spans: As etapas técnicas intermediárias que compõem o trace (como o tempo de busca semântica no banco vetorial, a validação de parâmetros via Pydantic ou a execução de código Python).
3. Generations: As chamadas concretas aos modelos de linguagem de fundação, gravando o prompt exato enviado, o texto retornado, o número preciso de tokens de entrada e saída (input/output tokens) e o custo financeiro em centavos de dólar calculado por modelo.

2. Soberania de Dados e LGPD no Brasil: O Risco de Plataformas SaaS Estrangeiras

Muitas empresas utilizam serviços de observabilidade em nuvem (SaaS) sediados nos Estados Unidos ou Europa sem avaliar os impactos regulatórios. Para rastrear uma chamada de IA, a biblioteca cliente envia todo o conteúdo do prompt e da resposta gerada para os servidores da plataforma de observabilidade:

Ao optar por hospedar o Langfuse em sua própria VPS sem fidelidade no Brasil em São Paulo, todo o banco de dados de telemetria, traces e históricos de prompts permanece sob sua custódia exclusiva. Os dados nunca saem da sua rede privada, eliminando riscos jurídicos e garantindo auditoria completa para clientes corporativos exigentes.

3. A Arquitetura do Langfuse v3 Self-Hosted: O Casamento entre ClickHouse e PostgreSQL

Em sua versão 3, o Langfuse passou por uma reformulação profunda de engenharia para suportar cargas massivas de bilhões de eventos diários sem perder agilidade:

[SDKs / Agentes: Python / Node.js / n8n / LangChain]
                         │
                         ▼ (HTTPS / API de Ingestão Assíncrona)
[Langfuse Web & Worker Service (Next.js / Node.js)]
   ├── Filas Assíncronas de Alta Velocidade ──► [Redis 7 em Memória]
   ├── Metadados, Auth, RBAC e Prompts ──► [PostgreSQL 16 Relacional]
   ├── Eventos de Telemetria e Analytics ──► [ClickHouse Colunar de Alta Compressão]
   └── Armazenamento de Payloads Brutos ──► [MinIO / Armazenamento S3 Local]
  

• ClickHouse (Banco Colunar): Responsável exclusivo pela gravação dos bilhões de spans, traces e scores. Por armazenar dados por coluna com altíssima taxa de compressão (ZSTD), o ClickHouse executa agregações financeiras e filtros de latência sobre milhões de registros em menos de 100 milissegundos, sem onerar a CPU do servidor.
• PostgreSQL 16 (Banco Relacional): Cuida das tabelas com consistência transacional: gerenciamento de usuários, permissões de equipe (RBAC), chaves de API do Langfuse e o versionamento de prompts.
• Redis 7: Atua como buffer assíncrono entre a API de ingestão e o ClickHouse, garantindo que picos de chamadas de agentes não causem lentidão nas aplicações clientes.
• MinIO: Fornece compatibilidade com API S3 dentro da própria VPS para persistir payloads brutos de imagens multimodais e saídas longas de áudio.

4. Deploy Completo com Docker Compose para VPS Linux KVM

Abaixo apresentamos o arquivo docker-compose.yml otimizado para executar o Langfuse v3 com limites de memória calibrados para operar com estabilidade em uma VPS KVM dedicada de 4GB a 8GB de RAM:

# docker-compose.yml - Langfuse v3 Self-Hosted na You Secure
version: '3.8'

services:
  langfuse_server:
    image: ghcr.io/langfuse/langfuse:3
    container_name: langfuse_app
    restart: always
    ports:
      - "127.0.0.1:3000:3000" # Exposto via Caddy com SSL Let's Encrypt
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://langfuse:KVMSecret2027@postgres:5432/langfuse_db
      - NEXTAUTH_URL=https://langfuse.seudominio.com.br
      - NEXTAUTH_SECRET=ChaveSuperSecretaNextAuth2027LangfuseHex
      - SALT=ChaveAleatoriaDeCriptografia2027Salt
      - TELEMETRY_ENABLED=false
      - CLICKHOUSE_URL=http://clickhouse:8123
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=ClickHouseSecret2027
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    networks:
      - langfuse_net
    depends_on:
      postgres:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    container_name: langfuse_postgres
    restart: always
    environment:
      POSTGRES_USER: langfuse
      POSTGRES_PASSWORD: KVMSecret2027
      POSTGRES_DB: langfuse_db
    volumes:
      - pgdata_langfuse:/var/lib/postgresql/data
    networks:
      - langfuse_net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U langfuse -d langfuse_db"]
      interval: 10s
      timeout: 5s
      retries: 5

  clickhouse:
    image: clickhouse/clickhouse-server:24.3-alpine
    container_name: langfuse_clickhouse
    restart: always
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
      - CLICKHOUSE_PASSWORD=ClickHouseSecret2027
    volumes:
      - chdata_langfuse:/var/lib/clickhouse
    networks:
      - langfuse_net
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: langfuse_redis
    restart: always
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
    networks:
      - langfuse_net
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

networks:
  langfuse_net:
    driver: bridge

volumes:
  pgdata_langfuse:
  chdata_langfuse:

5. Instrumentação Prática de Aplicações: Python, LangChain e n8n

A integração do Langfuse aos seus sistemas é extremamente limpa e não polui o código de negócio.

Instrumentação em Python com o Decorador @observe

O SDK oficial do Langfuse em Python fornece o decorador @observe(), que intercepta automaticamente entradas, saídas, exceções e tempos de resposta sem exigir alterações na lógica das funções:

# agent_tracing.py - Rastreamento com Langfuse na VPS
import os
from langfuse.decorators import observe, langfuse_context
from openai import OpenAI

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-sua-chave-publica"
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-sua-chave-secreta"
os.environ["LANGFUSE_HOST"] = "http://localhost:3000" # Servidor Local em SP

client = OpenAI()

@observe(name="calcular_limite_credito")
def calcular_score_financeiro(cpf: str) -> dict:
    # Etapa intermediária registrada como span
    langfuse_context.update_current_trace(user_id=f"user-{cpf[:3]}")
    return {"score": 850, "limite_aprovado": 15000.00}

@observe(name="fluxo_atendimento_credito")
def processar_solicitacao_cliente(mensagem_usuario: str, cpf: str):
    dados = calcular_score_financeiro(cpf)
    
    # Chamada ao modelo registrada como generation com contagem exata de tokens
    prompt = f"O cliente com score {dados['score']} perguntou: '{mensagem_usuario}'. Responda sobre seu limite."
    resposta = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.2
    )
    
    # Registra pontuação de qualidade se necessário
    langfuse_context.score_current_trace(name="conformidade_politica", value=1.0)
    return resposta.choices[0].message.content

if __name__ == "__main__":
    resp = processar_solicitacao_cliente("Quanto posso pegar de empréstimo?", "123.456.789-00")
    print("Resposta:", resp)

Integração com n8n AI Agents e Evolution API v3

Nas esteiras de automação corporativa, conectar o Langfuse à VPS para n8n e à VPS para Evolution API v3 permite:

1. Capturar as conversas do WhatsApp em tempo real e associá-las ao número de telefone do cliente como user_id no Langfuse.
2. Rastrear exatamente quais nós de IA no n8n demoraram mais para responder, identificando gargalos antes que os usuários reclamem de lentidão.
3. Auditar se o modelo tentou acessar ferramentas não autorizadas durante o diálogo, bloqueando tentativas de injeção de prompt (Prompt Injection).

6. Gestão e Versionamento Colaborativo de Prompts (Prompt Management)

Em muitas equipes, alterar o tom de voz do assistente virtual ou corrigir uma instrução desatualizada exige que um desenvolvedor edite o código-fonte, abra um pull request, aguarde o pipeline de CI/CD e faça um novo deploy na nuvem.

Com a funcionalidade de Prompt Management do Langfuse, seus prompts são armazenados centralmente no PostgreSQL 16 da VPS com controle de versões (ex: versão v1.0, v1.1, production). Pelo painel visual, engenheiros de prompt e analistas de produto ajustam os textos, testam variações em playground e promovem a versão de produção com um clique. A aplicação consome a versão mais recente em tempo de execução via API local sem downtime.

7. Dimensionamento de Hardware e Requisitos para Produção

O Langfuse v3 é surpreendentemente eficiente quando comparado a soluções de telemetria baseadas em Java ou Elasticsearch. A combinação de ClickHouse e PostgreSQL consome memória de forma controlada:

• 4 vCPUs KVM dedicadas: Processamento confortável para gerenciar centenas de requisições por segundo de ingestão de telemetria sem engasgos.
• 4GB de Memória RAM: Aloca 1GB para o ClickHouse, 768MB para o PostgreSQL 16, 256MB para o Redis e 1,5GB para o container Web/Worker do Langfuse e o proxy reverso.
• 100GB em discos NVMe de alta velocidade: Garante gravações em disco ultra-rápidas para o ClickHouse e o PostgreSQL, suportando meses de dados analíticos sem perda de performance.

Veja o comparativo completo de desempenho e estabilidade em nossa lista dos Melhores VPS do Brasil com suporte total a Docker e isolamento por virtualização KVM.