Probado con Langfuse 4.37.0 · ClickHouse 25.12 · PostgreSQL 17 · Python SDK 4.15.4 · verificado

Actualizado: 2026-09-16

Langfuse es una plataforma de código abierto que registra todo lo que hace tu agente de IA: cada llamada al modelo, su coste, su latencia y su resultado. Así puedes depurarlo y evaluarlo con datos, no a ciegas. Lo mejor es que puedes autoalojarla entera con Docker Compose y que tus trazas nunca salgan de tu servidor.

En esta guía verás qué es Langfuse y cómo desplegar su versión 4: la v4.37.0, que instalamos y probamos el 16 de septiembre de 2026. También verás su modelo de datos (trazas, spans y generaciones), cómo instrumentar un agente con OpenTelemetry y cómo montar evaluaciones con datasets. La misma explicación está disponible en inglés.

Puntos clave

  • Langfuse es una plataforma de ingeniería de LLM de código abierto (licencia MIT, salvo las carpetas ee/ de funciones empresariales) con más de 34 600 estrellas en GitHub. Su rama estable es la v4, que salió el 29 de julio de 2026; la última versión, la v4.37.0, es del 16 de septiembre de 2026.
  • Es autoalojable: un docker compose up levanta la interfaz web en el puerto 3000 con cuatro almacenes detrás, así que tus trazas se quedan en tu infraestructura. La v4 exige ClickHouse 25.12 o superior.
  • Su modelo de datos son las observaciones de tipo span (una unidad de trabajo) y generación (una llamada al modelo, con sus tokens, coste y latencia), agrupadas en trazas; en la v4 cada traza se representa con su observación raíz.
  • Instrumentar un agente es cuestión de un decorador: el SDK de Python v4 (la 4.15.4 a 16 de septiembre de 2026) está construido sobre OpenTelemetry, el estándar abierto de trazabilidad, y trae integraciones directas con OpenAI, LangChain, LiteLLM y LlamaIndex.
  • Va más allá del registro: gestiona prompts, guarda datasets de prueba y ejecuta evaluaciones (incluido el juez LLM) para comparar versiones de tu agente con métricas objetivas.

¿Qué es Langfuse?

Langfuse es una plataforma de observabilidad y evaluación para aplicaciones que usan modelos de lenguaje. Su propia documentación la define como «una plataforma de ingeniería de LLM de código abierto». Va más allá de las métricas de sistema como la CPU o la memoria. Entiende los conceptos propios de un agente de IA: los prompts, las respuestas del modelo, los tokens consumidos, el coste en dólares y las herramientas que invoca.

El problema que resuelve es concreto. Cuando un agente construido con el SDK de Anthropic o un grafo de LangGraph se comporta mal, un print en la consola no te sirve de nada. No ves qué prompt exacto recibió el modelo, cuántas iteraciones dio el bucle ni cuánto te costó cada intento. Langfuse graba ese árbol de ejecución completo y te lo muestra en una línea de tiempo navegable.

El proyecto nació en la aceleradora Y Combinator (promoción de invierno de 2023). En enero de 2026 anunció que ClickHouse lo había comprado, sin cambios inmediatos para quien lo usa y con el compromiso de seguir con el código abierto y el autoalojamiento. Su código es libre bajo licencia MIT, con la única excepción de las carpetas ee/, que agrupan funciones empresariales sujetas a una clave de licencia. Todo lo que necesitas para observar y evaluar agentes está en la parte abierta.

Desplegarlo con Docker Compose

La gran ventaja de Langfuse frente a un servicio en la nube es que puedes ejecutarlo entero en tu propia máquina. Ni los prompts ni las respuestas de tus usuarios abandonan tu red. Necesitas Git y Docker con Compose; para una máquina virtual, la documentación recomienda al menos 4 núcleos y 16 GiB de memoria. Clona el repositorio en la etiqueta de la versión que vas a desplegar:

git clone --depth 1 --branch v4.37.0 \
  https://github.com/langfuse/langfuse.git
cd langfuse

El docker-compose.yml marca con # CHANGEME cada secreto que debes cambiar antes de arrancar (grep -n CHANGEME docker-compose.yml los lista). Todos se leen de variables de entorno, así que no hace falta editar el YAML: Compose lee un fichero .env situado junto a él, como explicamos en variables de entorno y secretos en Docker Compose. Este bloque genera esos valores con openssl:

PG=$(openssl rand -hex 16); CH=$(openssl rand -hex 16)
MINIO=$(openssl rand -hex 16); REDIS=$(openssl rand -hex 16)
cat > .env <<EOF
NEXTAUTH_SECRET=$(openssl rand -hex 32)
SALT=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$PG
DATABASE_URL=postgresql://postgres:$PG@postgres:5432/postgres
CLICKHOUSE_PASSWORD=$CH
MINIO_ROOT_PASSWORD=$MINIO
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=$MINIO
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=$MINIO
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY=$MINIO
REDIS_AUTH=$REDIS
EOF

Las imágenes están en Docker Hub (langfuse/langfuse y langfuse/langfuse-worker), pero el compose las pide a docker.langfuse.com, un registro de Reo.dev, el proveedor de analítica de Langfuse, que cuenta cada descarga. Las etiquetas y los digests son idénticos por las dos vías. En nuestra máquina de pruebas ese dominio resolvía a 0.0.0.0 y el docker pull fallaba, así que descargamos de Docker Hub quitando el prefijo.

El compose usa la etiqueta flotante :4. El 16 de septiembre de 2026, latest, 4 y 4.37.0 apuntaban al mismo digest, y 3 a la v3.225.8. Para fijar la versión exacta, añade un docker-compose.override.yml, que Compose combina con el fichero principal:

services:
  langfuse-web:
    image: langfuse/langfuse:4.37.0
  langfuse-worker:
    image: langfuse/langfuse-worker:4.37.0

La web (3000) y la API S3 de MinIO (9090) escuchan en todas las interfaces, y el resto de puertos (3030, 5432, 6379, 8123, 9000 y 9091), solo en 127.0.0.1. En la máquina de pruebas otro servicio ocupaba el 9000, así que remapeamos los puertos con listas ports: !override en el override. Si cambias el 3000 o el 9090, ajusta también NEXTAUTH_URL y LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT en el .env. Arranca la pila y comprueba que la web responde:

docker compose up -d
curl -s http://localhost:3000/api/public/health

La respuesta (en nuestro puerto remapeado) confirma la versión desplegada:

{"status":"OK","version":"4.37.0"}

Detrás de esa única orden se levantan cuatro almacenes, cada uno con su cometido. Postgres guarda los datos transaccionales (usuarios, proyectos, prompts) y ClickHouse es la base de datos analítica que absorbe el gran volumen de trazas. Redis hace de caché y de cola de eventos, y un almacenamiento compatible con S3 (por defecto, un contenedor de MinIO con la imagen de Chainguard) retiene los eventos en bruto y los adjuntos. La v4 pide como mínimo ClickHouse 25.12 (recomienda la 26.4), Postgres 15 y Redis 7.0, y el compose trae ClickHouse 25.12, Postgres 17 y Redis 7.

Con las imágenes ya descargadas, la web aplicó las migraciones y escribió Ready en su log 10 s después del docker compose up -d, en un arm64 de 18 núcleos con carga media de 2,9. En una segunda instalación limpia, con la carga en 42, tardó 14 s (la documentación calcula de 2 a 3 minutos). Recién arrancados, los seis contenedores sumaban entre 2,3 y 2,6 GiB de memoria.

En esa segunda instalación, el worker intentó cargar los precios de los modelos antes de que la web terminara las migraciones, y las generaciones llegaban sin coste. Como solo lo intenta al arrancar, revisa su log y, si ves Error upserting default model prices, reinícialo:

docker compose logs langfuse-worker | grep "model prices"
docker compose restart langfuse-worker

Tras el reinicio, el log mostró Finished upserting default model prices y las trazas nuevas ya traían su coste; las anteriores se quedaron sin él.

El docker compose que trae el repositorio está pensado para pruebas y despliegues pequeños: no incluye alta disponibilidad, escalado horizontal ni copias de seguridad (para eso está el chart de Kubernetes). Con los contenedores arriba, abre http://localhost:3000, crea la primera cuenta y un proyecto, y anota el par de claves de API (pk-lf-… y sk-lf-…) que usarás para enviar trazas. También puedes crearlos al arrancar con las variables LANGFUSE_INIT_* de la inicialización sin interfaz, que es lo que hicimos en la prueba.

Si ya tienes una instalación v3, fíjala en la etiqueta 3 y no uses latest, que hoy descarga la v4. La migración exige subir antes ClickHouse y hacer copia de Postgres y ClickHouse, porque no hay vuelta atrás automática; lo detallamos en cómo migrar Langfuse de v3 a v4.

Trazas, spans y generaciones

Para sacar partido a Langfuse conviene tener claro su modelo de datos, que la v4 ha simplificado. Cada paso de tu aplicación es una observación (observation). La traza (trace) agrupa las observaciones que comparten el mismo trace_id y representa una petición completa, por ejemplo «el usuario preguntó X y el agente respondió Y». Estos son los tres tipos fundacionales de observación (Langfuse suma también tipos más especializados como agent, tool, retriever o guardrail para trazar pasos concretos de un pipeline):

  • Span: una unidad de trabajo con duración, como un paso de recuperación en una base de datos vectorial o la ejecución de una herramienta. Los spans se anidan y forman el árbol de la ejecución.
  • Generación (generation): un tipo especial de span para las llamadas al modelo. Captura el modelo usado, el prompt de entrada, la respuesta, los tokens de entrada y salida, el coste calculado y la latencia.
  • Evento (event): un punto concreto en el tiempo, sin duración, para marcar hitos.

En la v4, Langfuse guarda cada observación en una tabla ancha de ClickHouse (events_full) que repite en cada fila los atributos de su traza, como el usuario, la sesión o las etiquetas. La traza ya no es una entidad aparte: la representa su observación raíz. La interfaz sustituye la tabla de trazas por una única vista de Observaciones, filtrada por defecto a las raíces para mostrar una fila por traza. En nuestra instalación recién creada, ClickHouse ya tenía las tablas events_full y events_core.

Por encima de las trazas, las sesiones agrupan las trazas de una misma conversación. Las puntuaciones (scores) adjuntan un valor de calidad, numérico, categórico o booleano, que puede venir de un usuario, de una regla o de un modelo juez. Con esas cuatro piezas (trazas, observaciones, sesiones y puntuaciones) se describe cualquier aplicación de IA, desde un chatbot simple hasta un sistema multiagente al estilo de CrewAI.

Instrumentar un agente con OpenTelemetry

El SDK de Python de Langfuse va por la v4 (la 4.15.4 salió el 16 de septiembre de 2026) y está construido sobre OpenTelemetry, el estándar abierto de trazabilidad. Así no te ata a un formato propietario. Con un servidor v4, el SDK v3 queda como obsoleto, y para ver los datos en tiempo real necesitas la 4.7.0 o superior. Se instala con una orden, junto al cliente de OpenAI que usa el ejemplo:

pip install langfuse==4.15.4 openai

La forma más directa de instrumentar código es el decorador @observe(): envuelve cualquier función y Langfuse crea automáticamente un span con sus argumentos de entrada y su valor de retorno. Para las llamadas al modelo hay un atajo aún mejor: importar el cliente de OpenAI desde langfuse.openai convierte cada petición en una generación completa sin tocar nada más.

from langfuse import get_client, observe
from langfuse.openai import openai  # cliente de OpenAI ya instrumentado

@observe()
def responder(pregunta: str) -> str:
    # Esta llamada se registra sola como una generacion,
    # con modelo, tokens, coste y latencia incluidos.
    respuesta = openai.chat.completions.create(
        model="gpt-5.6-luna",
        messages=[{"role": "user", "content": pregunta}],
    )
    return respuesta.choices[0].message.content

print(responder("Resume que es la observabilidad de agentes"))
get_client().flush()

Configura LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY y LANGFUSE_BASE_URL (tu http://localhost:3000), además de OPENAI_API_KEY. El nombre antiguo LANGFUSE_HOST está marcado como obsoleto, aunque la 4.15.4 aún lo lee. El flush() final envía las trazas pendientes antes de que termine un script corto.

Lo probamos con un servidor local que imita la API de OpenAI, sin llamar a OpenAI. La API de observaciones v2 devolvió el span responder como raíz y la generación con el modelo gpt-5.6-luna, sus tokens y su coste, calculado con la tabla de precios integrada. Los endpoints antiguos, como GET /api/public/traces, devolvieron 404 en esta instalación nueva, así que consulta la v2:

curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_BASE_URL/api/public/v2/observations?fields=core,basic,model,usage"

Si ya usabas OpenTelemetry, ten en cuenta que el SDK v4 ya no exporta todos los spans. Por defecto envía los de Langfuse, los que llevan atributos gen_ai.* (las convenciones semánticas GenAI de OpenTelemetry) y los de bibliotecas de LLM conocidas. Para recuperar los de HTTP o base de datos, crea el cliente con Langfuse(should_export_span=lambda span: True).

Evaluaciones y datasets

Observar es el primer paso; el segundo es medir si tu agente mejora o empeora cuando cambias un prompt o un modelo. Langfuse resuelve esto con dos herramientas que trabajan juntas. Un dataset es una colección de casos de prueba, cada uno con una entrada y, opcionalmente, la salida esperada. Puedes crearlo a mano o promover a él las trazas reales que más te interesen desde la interfaz.

Sobre ese dataset lanzas un experimento: tu agente procesa cada caso y Langfuse guarda cada resultado como una traza enlazada al dataset. Después aplicas evaluadores que asignan puntuaciones. Pueden ser comprobaciones deterministas (evaluadores de código en Python o TypeScript) o un juez LLM, es decir, otro modelo que valora la corrección o el tono con una rúbrica. En la v4 los evaluadores trabajan sobre observaciones: los de nivel de traza aparecen como Legacy y dejan de ejecutarse cuando la instalación pasa al modo de escritura por defecto.

La interfaz compara dos ejecuciones lado a lado, así que ves de un vistazo si la versión nueva del prompt sube o baja la puntuación media. Es el mismo rigor que aplicarías al servir un modelo con vLLM en producción, pero aplicado a la calidad de las respuestas en lugar de al rendimiento del servidor.

Preguntas frecuentes

¿Es Langfuse realmente gratis y de código abierto?

Sí: el grueso de Langfuse, incluida toda la observabilidad, la gestión de prompts, los datasets y las evaluaciones, es software libre bajo licencia MIT, y puedes autoalojarlo sin pagar nada. La única excepción son las carpetas ee/ del repositorio (ee/, web/src/ee/ y worker/src/ee/), sujetas a una clave de licencia de pago. Esa clave desbloquea funciones empresariales como los roles por proyecto, los registros de auditoría o las políticas de retención de datos. Para observar y evaluar agentes no la necesitas.

¿Qué diferencia hay entre Langfuse y OpenTelemetry?

OpenTelemetry es un estándar abierto y un conjunto de bibliotecas para generar y transportar trazas, pero no incluye almacenamiento ni interfaz. Langfuse usa OpenTelemetry como base de su SDK y añade lo que falta: una base de datos especializada (ClickHouse), una interfaz para explorar las trazas y las capas de evaluación y gestión de prompts. En resumen, OpenTelemetry produce las trazas y Langfuse las recibe, las guarda y te deja trabajar con ellas.

¿Sigue teniendo soporte Langfuse v3?

Sí: según la guía oficial de migración, la v3 recibirá parches de seguridad hasta finales de enero de 2027. La última de esa rama, la v3.225.8, salió el 16 de septiembre de 2026 con tres correcciones portadas desde la v4, una de ellas de seguridad. Para migrar, sube antes ClickHouse a la 25.12, deja terminar las migraciones en segundo plano y haz una copia de Postgres y ClickHouse. Después arranca la v4 en modo legacy o dual, que mantiene los endpoints de lectura antiguos y los evaluadores de nivel de traza hasta que pases a events_only.

¿Puedo usar Langfuse con modelos locales?

Sí. Como el SDK instrumenta tu código, no el proveedor, funciona con cualquier modelo. Eso incluye los que ejecutas en tu propia máquina con Ollama (la herramienta que descarga y sirve modelos de lenguaje open source en tu propio equipo) a través de su API compatible con OpenAI. Autoalojando Langfuse y sirviendo el modelo de forma local consigues una plataforma de agentes completa en la que ningún dato sale de tu red, algo clave en entornos con requisitos estrictos de privacidad.

Si todavía estás decidiendo qué backend usar, la comparativa completa está en herramientas de observabilidad de agentes de IA, con licencias, auto-hospedaje y en qué caso falla cada una.

Conclusión

Langfuse cubre el hueco entre «mi agente funciona en mi portátil» y «mi agente funciona en producción y sé por qué». Con un docker compose up tienes una plataforma de observabilidad completa, que en la v4 guarda todo como observaciones en ClickHouse.

Graba cada traza, span y generación y calcula el coste y la latencia de cada llamada. Te deja evaluar cambios con datasets y un juez LLM, todo dentro de tu propia red y con licencia MIT. El siguiente paso es clonar el repositorio en la etiqueta v4.37.0, generar los secretos y levantar los contenedores. Después, instala el SDK con pip install langfuse y añade un @observe() a la primera función de tu agente para ver aparecer tu primera traza.

Fuentes

  1. Documentación oficial de Langfuse
  2. Langfuse en GitHub
  3. Versiones del SDK de Python de Langfuse
  4. OpenTelemetry, el estándar de trazabilidad
  5. Notas de la versión v4.0.0 de Langfuse
  6. Notas de la versión v4.37.0 de Langfuse
  7. Guía oficial de migración de Langfuse v3 a v4
  8. Despliegue de Langfuse con Docker Compose
  9. Contenedores e imágenes de Langfuse
  10. Migración del SDK de Python de v3 a v4
  11. Langfuse se une a ClickHouse
  12. Funciones de la licencia Enterprise de Langfuse

Ruta: Agentes de IA en producción: evaluación y fiabilidad