Langfuse: tracing open-source para apps LLM

Los logs de toda la vida se diseñaron para código determinista: misma entrada, misma salida, así que un stack trace más la entrada te reproducen el bug. Las apps LLM rompen esa promesa. El mismo prompt puede devolver otra respuesta, una tool dispara en una corrida y en la siguiente no, y el fallo casi nunca es una excepción, es una respuesta segura pero equivocada que se veía bien hasta que un usuario se quejó. Langfuse existe para cerrar esa brecha: captura cada llamada al modelo y cada ejecución de tool como un span dentro de una traza, así abres una corrida y lees de punta a punta exactamente qué vio e hizo el modelo. En este artículo vamos a ver qué es Langfuse en realidad, cuándo vale la pena frente a armar tu propia tabla o irte a un competidor hosteado, un quickstart real que puedes pegar en un servicio TypeScript, y las concesiones que nadie pone en el README, sobre todo la dependencia de ClickHouse que te cambia por completo un deploy en un solo VPS.

01 · Qué es en realidad

Langfuse son dos cosas bajo un mismo logo: un SDK con el que envuelves tus llamadas al LLM, y un servidor (UI más almacenamiento) que recibe y renderiza las trazas resultantes. El modelo mental viene del distributed tracing, acotado al trabajo con LLM.

• Una traza es una operación lógica: un turno de chat, una corrida de agente, una ronda de negociación.
• Una generation (un tipo de span) es una llamada al modelo dentro de ella: entrada, salida, id del modelo, params, uso de tokens y costo.
• Un span es cualquier otro paso: la ejecución de una tool, un retrieval, un paso de parseo.

Anidados bajo una traza, forman un árbol. Abre la traza de una corrida de agente que falló y vas a ver la llamada del planner, la tool de búsqueda que invocó, el resultado vacío que le volvió, y la siguiente llamada donde alucinó para tapar ese vacío, todo en orden, con tiempos y costo de tokens en cada nodo. Ese árbol es el producto. Todo lo demás (gestión de prompts, evals, dashboards) cuelga de ahí.

02 · Por qué importa en agentes

Un solo chat completion rara vez necesita una traza; un agente de varios pasos siempre. Los agentes fallan de maneras que los logs de toda la vida esconden por su propia estructura. Una tool devolvió basura tres pasos atrás y el modelo siguió construyendo encima tan tranquilo. Un bucle de reintentos disparó cuatro veces y quemó tokens en silencio. Un retrieval volvió vacío y el modelo llenó el hueco inventando. Ninguno de estos casos lanza una excepción. En un log plano son una pared de líneas sin relación padre-hijo, así que no hay forma de saber qué llamada causó cuál.

Un árbol de trazas te devuelve la causalidad. Dejas de preguntarte "por qué el modelo está tan bruto" y empiezas a leer "la búsqueda no devolvió nada y entonces el planner se inventó un resultado", que es un bug común y corriente, perfectamente arreglable, no un misterio.

Scores y versiones, no corazonadas

La segunda razón por la que Langfuse importa es la medición. Puedes adjuntar un score a cualquier traza, de un revisor humano o de un juez LLM, y puedes registrar una versión de prompt para que cada traza guarde con qué versión se generó. Juntas, te dejan responder la pregunta que todo cambio de prompt trae consigo: ¿de verdad mejoró la calidad, o solo se sintió mejor en los tres ejemplos que probé? Cuando ajusto un prompt para algo como la práctica de negociación de Proyección, la única respuesta honesta sale de los scores adjuntos a las trazas a lo largo de las versiones, no de mi instinto después de un puñado de corridas.

03 · Cuándo usarlo (y cuándo no)

Usa Langfuse cuando:

1. Tu app tiene más de una llamada al modelo por request, agentes, cadenas, flujos con retrieval.
2. Necesitas costo y latencia por paso, no solo la factura mensual del proveedor.
3. Quieres comparar versiones de prompts o correr evals sobre tráfico real de producción, no sobre un set de pruebas estático.

Usa otra cosa cuando:

• Es un solo completion y ya guardas registros estructurados. Una tabla en Postgres con el prompt resuelto, la respuesta cruda, tokens y latencia quizás sea todo lo que necesitas. No metas ClickHouse para tracear una sola llamada.
• Vives metido por completo en el tooling de un cloud. Si tu equipo ya vive dentro de un producto de observabilidad hosteado, un segundo panel puede costarte más en cambio de contexto del que te ahorra.
• No te da el presupuesto operativo. Auto-hospedar Langfuse no sale gratis ni en RAM ni en atención; mira la sección 05.

04 · Quickstart

El SDK de TypeScript es la vía más rápida para ver el valor por ti mismo. Instálalo, apúntalo a tu instancia con variables de entorno, y envuelve una llamada. Configura las llaves con LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY y LANGFUSE_BASEURL (esta última apunta a tu servidor self-hosted o al host de su cloud).

npm install langfuse

Luego crea una traza, registra una generation dentro de ella, y cierra el span con la salida. El hábito que vale la pena agarrar es una traza por corrida lógica, con cada llamada al modelo y cada tool como span hijo debajo.

import { Langfuse } from "langfuse"
import Anthropic from "@anthropic-ai/sdk"

const lf = new Langfuse()
const anthropic = new Anthropic()

async function negotiationTurn(userId: string, input: string) {
  const trace = lf.trace({ name: "negotiation-run", userId })

  const gen = trace.generation({
    name: "draft-reply",
    model: "claude-sonnet-4-5",
    input,
  })

  const res = await anthropic.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: input }],
  })

  gen.end({
    output: res.content,
    usage: {
      input: res.usage.input_tokens,
      output: res.usage.output_tokens,
    },
  })

  await lf.flushAsync()
  return res
}

Dos cosas que conviene grabarse. Primero, el SDK agrupa y envía en segundo plano, así que en contextos de vida corta (una función serverless, un script) tienes que llamar a flushAsync antes de que el proceso termine, o vas a perder la cola de tus trazas. Segundo, pásale a end el uso real de tokens que viene en la respuesta del proveedor, Langfuse puede estimar el costo, pero darle los conteos reales hace que tu dashboard de costo sea confiable y no apenas aproximado.

05 · Las concesiones que nadie pone en el README

Los problemas honestos, ordenados por qué tan seguido te muerden.

El self-host ahora son dos bases de datos, no una. Las versiones actuales de Langfuse separan el almacenamiento: Postgres para los datos transaccionales y ClickHouse para la parte analítica, la que da agregaciones rápidas sobre millones de spans. Arquitectónicamente es una decisión sólida, pero significa que el footprint del self-host es un stack de varios contenedores (Postgres, ClickHouse, el servidor web, un worker, casi siempre Redis y blob storage), no una sola imagen chiquita. En un solo VPS te toca calcular la RAM a conciencia, ClickHouse en particular consume mucha memoria.

El SDK de dispara-y-olvida puede botar trazas en silencio. Ese mismo diseño async que mantiene el logging fuera del camino del request también hace que un flush que se te olvidó o una cola saturada pierdan trazas sin lanzar ningún error. Es la concesión correcta, que el request del usuario se complete pesa más que capturar su traza, pero quiere decir que Langfuse es una ayuda de observabilidad, no un libro contable apto para facturar. Guarda los números de costo de referencia en algún lado que tú controles.

Las trazas son un pasivo de privacidad por defecto. Una traza contiene el prompt y la respuesta en crudo, lo que para la mayoría de apps significa datos personales metidos en tu almacén analítico. Enmascara o hashea los campos sensibles antes de que salgan de tu servicio, ponle una ventana de retención, y cierra quién puede leer el proyecto. Un almacén de trazas sin proteger es una de las brechas más fáciles en las que caer, justamente porque se siente como "son solo logs".

El desfase de versión entre SDK y servidor es real. Como el formato va evolucionando, un SDK demasiado nuevo contra un servidor self-hosted viejo puede dejarte huecos confusos. Fija las versiones y sube el servidor y el SDK juntos en vez de dejar que se desfasen.

Langfuse es la herramienta que quiero montada antes del primer resultado raro en producción, no atornillada a las apuradas durante el incidente. El árbol de trazas se paga solo la primera vez que convierte un "el modelo está actuando raro" en un bug de una línea que puedes señalar con el dedo. Eso sí, entra con los ojos bien abiertos: el SDK es fácil, el self-host es un stack en serio, y las trazas son datos sensibles que ahora son tuyos.