Cómo alojar Langfuse para rastrear agentes de IA

Por qué rastrear un agente de IA

Puede alojar Langfuse para ver qué hizo realmente su agente durante una ejecución. Langfuse es una herramienta de observabilidad de LLM (modelo de lenguaje grande) de código abierto. Registra cada prompt, cada respuesta del modelo, cada llamada a una herramienta y cada token. Después, agrupa todos esos datos en un único trace que puede abrir y revisar. Si lo ejecuta en su propio VPS, esos prompts nunca salen de un servidor bajo su control.

El motivo es sencillo. No puede corregir un problema de costes o de calidad que no puede ver. La factura del proveedor indica que el martes gastó cuatro veces más que el lunes. Un trace indica qué ejecución del agente lo causó, qué prompt creció hasta 40,000 tokens y qué bucle de reintento se ejecutó nueve veces antes de abandonar. La factura proporciona la cifra. El trace muestra el código que la produjo.

Esta guía utiliza tres términos. Un trace es una ejecución completa del agente, de principio a fin. Una observation es un paso dentro de esa ejecución: un span para el código normal y una generation para una llamada a un modelo. Un score es un número asociado a un trace, procedente de una revisión humana o de un evaluador automatizado. Langfuse es compatible con OpenTelemetry (OTel), el estándar independiente del proveedor para el rastreo distribuido. Por tanto, la instrumentación que ya tenga puede enviar datos a Langfuse.

Qué ejecuta realmente Langfuse autohospedado

Langfuse v4 no es un solo contenedor. Consta de dos contenedores de aplicaciones y cuatro servicios de almacenamiento. En un VPS único, los seis se ejecutan en el servidor.

• langfuse-web sirve la interfaz web y la API de ingesta.
• langfuse-worker vacía la cola en segundo plano. Analiza los lotes de ingesta, calcula el coste y ejecuta el trabajo nocturno de retención.
• Postgres almacena datos transaccionales como usuarios, organizaciones, proyectos, claves de API y prompts.
• ClickHouse almacena los datos de trazas, es decir, las observaciones y las puntuaciones. Es un almacén de columnas diseñado para consultas analíticas. Por eso un panel sobre más de cien millones de filas sigue respondiendo rápidamente.
• Redis es la cola y la caché que se sitúan entre la aplicación web y el worker.
• MinIO proporciona almacenamiento de objetos compatible con S3 en el propio servidor. Almacena cada evento sin procesar recibido y cualquier archivo multimedia que adjunte.

Langfuse publica los recursos mínimos de cada componente que ejecuta. El gráfico muestra los tres que realizan el trabajo.

[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

ClickHouse por sí solo necesita 8 GiB de memoria. El contenedor web y el worker necesitan 4 GiB cada uno. Esos son los mínimos publicados para los 3 componentes del gráfico. La misma página indica 4 GiB para Postgres, 1.5 GiB para Redis o Valkey y 4 GiB para MinIO. Por tanto, los mínimos de los seis suman 25.5 GiB. La guía de Docker Compose del propio proyecto recomienda al menos 4 cores, 16 GiB de memoria y unos 100 GiB de almacenamiento para una sola máquina. Es menos que la suma de los mínimos de los componentes. Por eso, considere 16 GiB como el mínimo que necesita un servidor compartido con Compose, no como margen disponible.

No intente ejecutar esto en un plan de 2 GiB. ClickHouse se inicia y acepta escrituras durante un tiempo, pero después se detiene durante una operación de combinación en segundo plano porque una combinación carga partes grandes de una tabla en memoria. Verá que docker compose ps informa de que el contenedor de clickhouse está en estado restarting, mientras dmesg muestra una línea como Out of memory: Killed process 1234 (clickhouse-serv), y todos los paneles de Langfuse devuelven 500. Con una carga menor, ClickHouse rechaza la consulta y registra DB::Exception: Memory limit (total) exceeded. Planifique 16 GiB. Si el mismo VPS debe ejecutar otros servicios, reserve recursos adicionales para ellos. Incluso una pila relativamente ligera, como un espacio de trabajo AFFiNE autohospedado, necesita sus propios gigabytes, y ClickHouse no liberará memoria para ellos.

Implementar Langfuse con Docker Compose

Clone el repositorio. La pila, la configuración entre servicios y el entorno predeterminado están en su docker-compose.yml.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

Todos los valores que debe cambiar están marcados con # CHANGEME en ese archivo. Genere primero los tres secretos de la aplicación.

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY debe tener 256 bits escritos como 64 caracteres hexadecimales. Eso es exactamente lo que muestra openssl rand -hex 32. Cifra los valores confidenciales almacenados, incluidas las claves de proveedores de LLM que guarde en la instancia. Si lo cambia después de que existan datos, esas filas ya no se podrán descifrar. Trátelo como permanente desde el primer arranque. SALT se usa para aplicar un hash a las claves de API de Langfuse. Si lo cambia, invalida todas las claves que ya usan sus agentes.

Después, establezca POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH y MINIO_ROOT_PASSWORD. La contraseña de MinIO aparece en cuatro lugares: primero como MINIO_ROOT_PASSWORD y después como LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY y LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Si omite uno, MinIO rechaza ese cliente con SignatureDoesNotMatch. El mensaje aparece en el registro del worker, aunque la interfaz web siga funcionando con normalidad. Mantener estos valores en un archivo env, en lugar de incluirlos en el archivo compose versionado, es el patrón descrito en archivos env y secretos de Docker Compose.

Fijar las etiquetas de imagen antes de empezar

El archivo proporcionado usa docker.langfuse.com/langfuse/langfuse:4 y docker.langfuse.com/langfuse/langfuse-worker:4. Esas etiquetas cambian. Langfuse ejecuta automáticamente las migraciones de Postgres y ClickHouse al iniciar. Por eso, un docker compose pull rutinario unos meses después se convierte en una migración de esquema no planificada en una base de datos de la que no hizo una copia de seguridad esa mañana. Fije ambas imágenes a una misma versión en un docker-compose.override.yml. Compose lo combina sobre el archivo proporcionado, de modo que un git pull posterior no sobrescriba sus cambios. Las mismas imágenes se publican en Docker Hub, que es de donde las obtiene la sobreescritura siguiente.

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.72.0
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.72.0

La versión 4.3.1 era la versión 4.3 vigente en agosto de 2026. Desde entonces se han publicado versiones rápidamente, y v4.56.0 era la última disponible en GitHub el 11 de octubre de 2026. La sobreescritura anterior usa v4.72.0, la última disponible en GitHub el 31 de octubre de 2026. Consulte la página de versiones de GitHub del proyecto, fije la versión vigente el día del despliegue y cambie ese número de forma deliberada. Algunas imágenes de almacenamiento del archivo proporcionado también deberían tratarse de la misma manera, porque sus etiquetas cambian. postgres:17 (el valor predeterminado de una variable POSTGRES_VERSION) y redis:7 siguen una versión principal. El archivo proporcionado ahora usa una etiqueta de versión exacta para docker.io/clickhouse/clickhouse-server, con lo que fija una versión exacta de ClickHouse. Esta regla no es exclusiva de Langfuse: un rastreador de entrenamientos openGym autoalojado ejecuta una fracción de esta pila y aun así requiere una etiqueta de git con nombre, porque cualquier aplicación que migre su propia base de datos al iniciar puede convertir una extracción rutinaria en un cambio de esquema.

Inicie la pila.

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

El primer arranque ejecuta las migraciones, así que espere dos o tres minutos antes de comprobar si responde. El contenedor web registra Ready cuando está listo. docker compose ps debería mostrar seis servicios en estado running. Si un contenedor se reinicia continuamente, su registro contiene el motivo. Las migraciones de ClickHouse se aplican cuando se inicia el contenedor web. Por eso, un CLICKHOUSE_MIGRATION_URL incorrecto aparece en docker compose logs langfuse-web, no en el registro del worker que está siguiendo. Esa variable usa el protocolo nativo de ClickHouse en el puerto 9000, no el puerto HTTP 8123. Si la apunta a 8123, se interrumpen las migraciones de arranque del contenedor web. El worker ejecuta las migraciones en segundo plano, que tardan más. Por eso, sus mensajes aparecen en el registro del worker.

Compruebe el estado desde el propio servidor.

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

Una llamada simple a /api/public/health sólo demuestra que el proceso de API está activo, porque de forma predeterminada no comprueba la base de datos. La forma failIfDatabaseUnavailable=true es la adecuada para configurar en un monitor. Devuelve 503 cuando no se puede acceder a la base de datos. /api/public/ready devuelve 200 cuando el contenedor web está listo para recibir tráfico y 500 cuando se le ha indicado que se detenga. Ambas son comprobaciones HTTP normales. Por eso, una página de estado de Uptime Kuma puede supervisarlas e informarle de que la pila está caída antes que sus agentes.

Coloque TLS delante y cierre los puertos adicionales

El archivo de Compose incluido publica 3000:3000 para el contenedor web y 9090:9000 para MinIO. Ambos escuchan en todas las interfaces. En una IP pública, cualquiera que analice el puerto 3000 llega a la página de registro, y cualquiera que analice 9090 se comunica con el bucket que contiene sus prompts sin procesar.

Una regla del firewall no basta para cerrarlos. Docker escribe sus propias reglas DNAT en la tabla nat, y estas se evalúan antes de que las reglas de filtrado de ufw vean el paquete, por lo que ufw deny 3000 deja abierto el puerto publicado. Esto afecta a suficientes usuarios como para tener su propia guía: por qué los puertos publicados por Docker omiten ufw. En su lugar, escuche en loopback desde el archivo de override. Use !override con Docker Compose 2.24.4 o posterior para reemplazar los puertos publicados; una lista normal se combina con las asignaciones originales.

services:
  langfuse-web:
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports: !override
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL debe ser la dirección pública exacta, incluido el esquema, porque el flujo de inicio de sesión construye la URL de callback a partir de ese valor. Déjelo como http://localhost:3000 detrás de un proxy HTTPS y el flujo de ida y vuelta del inicio de sesión enviará el navegador a un destino que no puede alcanzar.

Ahora apunte un reverse proxy a 127.0.0.1:3000 y deje que gestione el certificado. Para Traefik en el mismo proyecto de Compose, enrute a langfuse-web:3000 a través de la red de Compose usando las etiquetas descritas en ejecutar varias aplicaciones detrás de un reverse proxy de Traefik. Caddy hace el mismo trabajo en dos líneas si Langfuse es el único servicio del equipo. Verifique con curl -sI https://langfuse.example.com/api/public/ready y confirme después desde otro equipo que curl http://YOUR_IP:3000 no puede conectarse.

Hay una consideración sobre MinIO. Langfuse entrega URLs prefirmadas que apuntan a ese endpoint S3, tanto a los SDK que cargan archivos multimedia como al navegador cuando los carga. Por tanto, si usa trazas multimodales con imágenes o audio, un MinIO limitado a loopback impedirá cargar esos archivos desde otros equipos o mostrarlos en el navegador. Consulte la página de configuración del almacenamiento de blobs antes de ponerlo detrás de un proxy, porque el endpoint escrito en la URL prefirmada, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, debe coincidir con el que publique. Las trazas de texto sin formato no se ven afectadas.

Cree su cuenta en la primera visita y mantenga después el control de la instancia. Configure AUTH_DISABLE_SIGNUP=true una vez creada la cuenta para que un usuario externo que llegue a la página no pueda registrarse. Langfuse también tiene LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, que limita quién puede crear organizaciones, pero es una función de Enterprise Edition y sólo entra en vigor con una clave de licencia. Si ya ejecuta Authentik como su propio proveedor de identidad, Langfuse admite una conexión OIDC estándar, por lo que las cuentas se crean y eliminan junto con el resto de sus aplicaciones, en lugar de mantenerse en una lista de contraseñas que sólo conoce este equipo.

Envía tu primera traza

Crea un proyecto en la interfaz web y copia sus claves pública y secreta desde la configuración del proyecto. El SDK de Python lee tres variables de entorno.

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL es el nombre de la variable en SDK v4, publicado en marzo de 2026. El código y las guías anteriores usan LANGFUSE_HOST. Si las trazas llegan a Langfuse Cloud en lugar de a tu servidor, la causa es que la URL base no está definida, porque el valor predeterminado apunta a la instancia alojada.

El SDK de Python v5 actual requiere Python 3.11 o posterior y Langfuse v4.59.0 o posterior en instalaciones autohospedadas. El servidor fijado anteriormente cumple este requisito.

pip install langfuse opentelemetry-instrumentation-anthropic anthropic

import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

El decorador @observe abre una observación alrededor de la función, captura sus argumentos y su valor de retorno, y la anida bajo la observación que ya esté activa. AnthropicInstrumentor es la instrumentación de OpenTelemetry para el cliente de Anthropic y convierte cada llamada messages.create en una generación que incluye el nombre del modelo, el uso de tokens y la latencia, sin modificar el punto donde se realiza la llamada.

Dos llamadas hacen las comprobaciones por ti. langfuse.auth_check() devuelve False si las claves no son válidas o la URL base es incorrecta. Esto es más rápido que averiguar por qué el panel está vacío. langfuse.flush() espera hasta que se envíen los spans en cola. Los procesos de corta duración lo necesitan, porque el SDK agrupa los spans en segundo plano y un script que termina inmediatamente se lleva consigo el lote que aún no se ha enviado. Si todo un equipo envía trazas en lugar de un solo script, define esas tres variables una sola vez en el gateway por el que ya pasan los agentes de todos, en lugar de definirlas en el shell de cada persona. Así es como un entorno OneCLI autohospedado mantiene instrumentadas las ejecuciones de todos los colaboradores mientras las claves permanecen en un único lugar.

¿Por qué ClickHouse sigue creciendo?

Las trazas son los datos que crecen más rápido entre los que la mayoría de las personas aloja por su cuenta. Cada ejecución de un agente escribe una fila por paso, y las entradas y salidas se almacenan completas. Por eso, un agente con mucha actividad y prompts largos produce muchos más bytes al día que la aplicación que supervisa. Si no se controla, ClickHouse llena el disco. Cuando el disco se llena, la ingesta se detiene en lugar de funcionar más lentamente.

Aquí crecen dos elementos distintos y cada uno necesita una solución diferente.

El primero son sus propios datos de trazas. La solución es configurar la retención. En una instancia autogestionada, la retención de datos es una función de Enterprise Edition y necesita una clave de licencia. Sin una licencia, Langfuse conserva las trazas, observaciones, puntuaciones y archivos multimedia indefinidamente. Por tanto, dimensione el disco para ese caso y confíe en la alerta de disco del final de esta sección. Con una licencia, los propietarios y administradores del proyecto abren la configuración del proyecto y establecen un periodo de retención de datos en días. Langfuse acepta un mínimo de 3 días. Cada noche, un trabajo selecciona las trazas, observaciones, puntuaciones y archivos multimedia que son anteriores a ese periodo y los elimina de ClickHouse y del almacenamiento de blobs, excepto los archivos multimedia asociados a elementos guardados de conjuntos de datos. El trabajo necesita el permiso DeleteObject en el bucket. Las credenciales de root de MinIO del archivo compose predeterminado ya tienen ese permiso. La eliminación es permanente. Configure primero una exportación al almacenamiento de blobs si necesita conservar el historial a largo plazo. No escriba manualmente cláusulas TTL en las tablas propias de Langfuse. El trabajo de retención mantiene sincronizados ClickHouse y el bucket, mientras que un TTL manual elimina los datos de un solo lado.

Elija el periodo según el uso real. La revisión de costes y calidad se hace con datos de días anteriores, no de meses anteriores. Treinta días es un punto de partida razonable para un equipo pequeño. Catorce días son suficientes si sólo abre una traza cuando algo falla.

El segundo elemento son las propias tablas de registros del sistema de ClickHouse. Esto sorprende a muchas personas porque el disco sigue creciendo después de configurar la retención. ClickHouse escribe trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log y latency_log para sus propios diagnósticos. Estas tablas se incluyen sin TTL y Langfuse nunca las lee. Primero averigüe dónde se ha usado realmente el disco.

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

Ejecútelo con docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Si las tablas del sistema están cerca de los primeros puestos, desactívelas con una sobrecarga de configuración. ClickHouse combina cada archivo de /etc/clickhouse-server/config.d/ con su configuración principal al iniciarse.

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
    <latency_log remove="1"/>
</clickhouse>

Móntelo y reinicie ClickHouse.

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

Esto detiene las nuevas escrituras. Las filas que ya están en el disco permanecen allí. Por tanto, recupere el espacio explícitamente con DROP TABLE IF EXISTS system.trace_log y haga lo mismo con cada tabla que haya eliminado. Si prefiere conservar los diagnósticos, la alternativa es configurar un TTL agresivo en cada tabla en lugar de remove="1". La documentación de escalado de Langfuse explica este procedimiento. Estas directivas TTL sólo se aplican cuando se crea por primera vez una tabla del sistema. En una instalación existente, la misma documentación explica también cómo aplicar el cambio posteriormente a las tablas.

Conviene conocer una tabla adicional. blob_storage_file_log registra los archivos de eventos cargados en el bucket. Si también configura una política de ciclo de vida en el bucket, establezca un TTL equivalente para la tabla. Así evitará que ambos elementos queden desincronizados.

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

Configure también una alerta sencilla df -h para el disco de datos. Las trazas no crecen de forma uniforme. Crecen el día que publica un agente nuevo, y la primera señal de ese crecimiento no debería ser un fallo de la ingesta.

Hacer copias de seguridad de Postgres y ClickHouse

Una copia de seguridad de Langfuse tiene tres partes. Postgres almacena los usuarios, las organizaciones, los proyectos y las claves de API. ClickHouse almacena las trazas. MinIO almacena los eventos sin procesar. Si restaura sólo Postgres, tendrá un inicio de sesión funcional, pero sin historial. Si restaura sólo ClickHouse, tendrá un historial que nadie podrá consultar porque no podrá iniciar sesión. Esta separación no es exclusiva de Langfuse. Un sistema Chatwoot de soporte autogestionado tiene la misma estructura: si crea un volcado de Postgres sin el directorio de cargas, se restauran las conversaciones, pero desaparecen todos sus archivos adjuntos.

Postgres es un pg_dump simple, que es lo que utiliza la documentación de copias de seguridad de Langfuse para una instalación de Docker.

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse requiere más cuidado porque copiar un directorio de datos activo mientras se ejecutan fusiones no produce una copia de seguridad coherente. En un solo servidor, el método sencillo consiste en detener el contenedor y archivar el volumen.

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

Use el nombre del volumen que muestra docker volume ls, no el que aparece escrito en YAML. El archivo declara langfuse_clickhouse_data, y Compose le añade como prefijo el nombre del proyecto. Por eso, un clon en un directorio llamado langfuse produce langfuse_langfuse_clickhouse_data. Si se equivoca, docker run crea un volumen nuevo y vacío sin mostrar ningún error, y el archivo contiene la nada.

Langfuse carga los datos de eventos sin procesar en el bucket con cada solicitud de ingesta y los vuelve a leer para reintentar los trabajos de ingesta fallidos. Por eso, una parada breve de ClickHouse normalmente sólo hace que el worker reintente los trabajos después. Hágalo en una hora de poca actividad y mantenga la parada lo más breve posible. En una instancia con más carga, la sentencia BACKUP DATABASE default TO S3(...) propia de ClickHouse escribe una copia de seguridad coherente sin detener el servidor. MinIO es la tercera pieza. mc mirror o la replicación de MinIO a un bucket externo cubren esa parte. Sea cual sea el método, saque las copias del servidor. Para eso sirven las copias de seguridad cifradas de restic en un VPS.

Redis almacena la cola y la caché. Si se pierde, se descartan los trabajos en cola, aunque sus archivos de eventos sin procesar sigan en el bucket.

La advertencia sobre la coherencia es real y conviene expresarla claramente. Postgres y ClickHouse se vuelcan en momentos diferentes. Por eso, una restauración puede dejar una fila de proyecto sin trazas, o trazas asociadas a un proyecto que ya no existe. Langfuse tolera esta situación, pero haga ambos volcados con poca diferencia de tiempo y durante un periodo de poco tráfico. El bucket de eventos es la verdadera red de seguridad porque Langfuse carga allí los datos de eventos sin procesar con cada solicitud de ingesta.

Restaure las copias en una pila de prueba al menos una vez. Así descubrirá ahora que el nombre del volumen es incorrecto, en lugar de descubrirlo durante una interrupción del servicio.

Qué revisar primero

Cuatro aspectos justifican su lugar durante la primera semana.

• Coste por traza. Langfuse calcula el coste a partir del nombre del modelo y del uso de tokens, así que ordene las trazas por coste y lea de principio a fin la más cara. Normalmente se debe a un prompt que ha crecido: un documento completo pegado en el contexto o un historial de conversación que nadie recorta. Cuando pueda verlo, controlar cuánto le cuesta un agente de IA se convierte en una tarea de ingeniería en lugar de una estimación.
• Uso de tokens separado entre entrada y salida. Los tokens de entrada son numerosos y baratos; los de salida son escasos y caros, y la entrada almacenada en caché es aún más barata. Esta misma contabilidad se explica en cómo se contabiliza el uso de tokens de Claude Code y se aplica a cualquier agente que escriba usted mismo.
• Percentiles de latencia. La mediana oculta el problema. Los valores p95 y p99 muestran dónde se producen los tiempos de espera agotados y, dentro del bucle de un agente, una llamada lenta a una herramienta en p95 se multiplica por el número de iteraciones.
• Llamadas fallidas a herramientas. Filtre las observaciones por nivel ERROR. Una herramienta que falla el 5% de las veces puede pasar desapercibida en la tasa de éxito agregada y resultar muy evidente en las trazas, donde puede ver que el modelo reintenta y después consume tokens para evitar el problema.

Establezca el periodo de retención y elija el panel que revisará semanalmente el mismo día en que haga el despliegue. Una herramienta de observabilidad que nadie abre es una base de datos que termina llenando un disco.

FAQ

¿Cuánta memoria necesita una instancia de Langfuse autohospedada?

Reserve 4 núcleos de CPU y 16 GiB de memoria, que es lo que recomienda la guía de Docker Compose de Langfuse para una sola máquina virtual, además de unos 100 GiB de almacenamiento. Los mínimos publicados para los componentes son 8 GiB para ClickHouse y 4 GiB para cada uno de los contenedores web y worker. La misma página indica 4 GiB para Postgres, 1.5 GiB para Redis y 4 GiB para MinIO. En total, los seis componentes requieren 25.5 GiB, más que los 16 GiB recomendados para Compose.

¿Por qué el disco de ClickHouse sigue llenándose después de configurar la retención de datos?

La configuración de retención sólo cubre los datos propios de Langfuse. ClickHouse escribe por separado sus tablas de diagnóstico trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log y latency_log, que no tienen TTL de forma predeterminada. Ejecute system.parts agrupado por tabla para ver cuál ocupa más espacio. Después, deshabilite las tablas que no use mediante una entrada remove="1" en un archivo situado bajo /etc/clickhouse-server/config.d/, reinicie ClickHouse y elimine las tablas existentes para recuperar el espacio que ya ocupan.

¿Cuál es el periodo mínimo de retención de datos en Langfuse?

Tres días. La retención se configura por proyecto en los ajustes del proyecto o mediante la API de Organization Management. Un trabajo nocturno elimina de ClickHouse y del almacenamiento de objetos las trazas, observaciones, puntuaciones y recursos multimedia anteriores a ese periodo, excepto los recursos multimedia asociados a elementos de conjuntos de datos guardados. En una instancia autohospedada, esta función pertenece a Enterprise Edition y requiere una clave de licencia. Sin ella, los datos se conservan indefinidamente. La eliminación no se puede deshacer. Configure primero una exportación al almacenamiento de objetos si necesita conservar el historial más allá de ese periodo.

¿Tengo que hacer copias de seguridad de Postgres y ClickHouse?

Sí, porque contienen datos distintos. Postgres contiene los usuarios, las organizaciones, los proyectos y las claves de API. ClickHouse contiene los datos de las trazas. Restaurar sólo Postgres produce una instancia en la que puede iniciar sesión, pero que no contiene datos de trazas. Haga también una copia de seguridad del bucket de MinIO, porque contiene los eventos sin procesar que Langfuse guarda al recibirlos. En esta arquitectura, es lo más parecido a una fuente de verdad.

¿Puedo dirigir una configuración existente de OpenTelemetry a una instancia de Langfuse autohospedada?

Sí. Langfuse v4 y sus SDK actuales se basan en OpenTelemetry, y las instrumentaciones OTel de Anthropic y OpenAI exportan los datos directamente a Langfuse. En Python, ejecute pip install langfuse opentelemetry-instrumentation-anthropic, llame a AnthropicInstrumentor().instrument() una vez durante el arranque y configure LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY y LANGFUSE_BASE_URL con su propio host. Confirme el resultado con langfuse.auth_check() antes de buscar un problema en un dashboard que no aparece.