Langfuse autohospedado: trazabilidad y coste de las solicitudes LLM

Qué configuramos y por qué

Langfuse es una plataforma de observability para aplicaciones con grandes modelos de lenguaje. Recibe eventos desde SDK, API o integraciones con LangChain, LlamaIndex, OpenAI SDK y otras bibliotecas. Después, en la interfaz web se puede ver el recorrido completo de una solicitud de usuario: el prompt de entrada, los pasos intermedios del pipeline RAG, las llamadas a herramientas, la respuesta del modelo, el consumo de tokens, el coste, la duración y los errores.

Un problema típico de una aplicación de IA es el siguiente: los usuarios se quejan de respuestas lentas, las facturas de la API aumentan y el desarrollador solo ve logs fragmentarios de la aplicación. Los logs convencionales no vinculan la solicitud del usuario, el retrieval desde la base vectorial, dos llamadas al modelo y la respuesta final en una sola entidad. Langfuse resuelve esto mediante trace, span y generation: trace describe el escenario de usuario, span una etapa técnica y generation una llamada concreta a un LLM.

Langfuse self-hosted es especialmente útil cuando los prompts o las respuestas contienen datos comerciales, datos personales, fragmentos de documentos de clientes, código fuente o conocimiento interno de la empresa. Con un despliegue propio, los eventos permanecen en tu infraestructura. Solo salen las solicitudes al proveedor del modelo que ya utilizas: por ejemplo, OpenAI, Anthropic o un endpoint en la nube de un modelo local.

Qué funcionará después de la configuración

• Creación de proyectos, entornos y claves API para development, staging y production.
• Trazabilidad de solicitudes mediante integraciones compatibles con Python, TypeScript u OpenTelemetry.
• Cálculo del coste de solicitudes por modelos y tokens de entrada y salida.
• Búsqueda de solicitudes lentas, erróneas y costosas.
• Almacenamiento de prompts con versiones y publicación de prompt templates.
• Evaluación de respuestas manualmente, mediante feedback de usuarios o LLM-as-a-judge.
• Exportación y análisis de datos mediante PostgreSQL, ClickHouse y API.

Cloud-managed o self-hosted

La opción self-hosted no elimina los requisitos de protección de datos. De forma predeterminada, Langfuse puede guardar las entradas y salidas de los modelos, lo que significa que pueden aparecer email, teléfonos, textos de contratos y otra información sensible. Antes de conectar tráfico de production, define el período de retención de eventos, excluye de los logs los campos innecesarios y añade el enmascaramiento de secretos en tu aplicación.

Regla práctica: envía a Langfuse suficiente contexto para depurar la calidad y el precio, pero no dupliques allí contraseñas, access tokens, números de tarjetas de pago ni documentos sin procesar si no son necesarios para el análisis.

Qué configuración de VPS se necesita para esta tarea

Langfuse no es un único contenedor. Para un funcionamiento normal se necesitan, como mínimo, la aplicación web y un worker, PostgreSQL para datos transaccionales, ClickHouse para eventos analíticos y Redis para colas y caché. En un solo VPS resulta conveniente para un equipo pequeño y un volumen moderado de trazas, pero los recursos deben planificarse con margen.

Una configuración inicial práctica es 4 vCPU, 8 GB de RAM, 100–160 GB NVMe y una conexión de 100 Mbit/s o más. Este servidor deja margen para PostgreSQL y ClickHouse, que son sensibles a la falta de memoria y a un disco lento. Como una de las opciones, puedes elegir un VPS con las características indicadas, pero es más importante comprobar el tipo de disco, la disponibilidad de copias de seguridad y la ubicación del servidor.

Por qué NVMe es más importante que un HDD grande

PostgreSQL escribe constantemente logs de transacciones y ClickHouse crea y fusiona partes de tablas. En un HDD, la interfaz de Langfuse puede seguir estando disponible, pero las consultas analíticas, la ingestión de eventos y las copias de seguridad serán considerablemente más lentas. Para una instancia de production, utiliza SSD o NVMe. Empieza con 100 GB si conservas las trazas durante 30 días; si las conservas seis meses, tienes payloads grandes y miles de solicitudes por hora, necesitarás bastante más.

Cuándo se necesita un dedicated en lugar de un VPS

Un servidor dedicado se justifica si recibes de forma constante cientos de miles o millones de eventos de observación al día, almacenas cadenas largas de agentes, ejecutas consultas analíticas pesadas o necesitas aislar los recursos de la base de datos de máquinas virtuales vecinas. Otro motivo es necesitar 64 GB de RAM y varios discos NVMe rápidos. Hasta ese momento, es más sencillo escalar el VPS: aumentar CPU y memoria, y mover ClickHouse o PostgreSQL a un servidor independiente.

Elección de la ubicación

La ubicación afecta a la latencia entre tu aplicación y Langfuse, los requisitos legales y el coste del tráfico entre regiones. Si el backend de la aplicación funciona en un centro de datos europeo, aloja Langfuse en la misma región: la trazabilidad añadirá milisegundos, no decenas de milisegundos. Si los eventos incluyen datos de usuarios europeos, comprueba los requisitos de GDPR, DPA y las políticas internas de retención de datos.

Preparación del servidor

A continuación se presupone un servidor limpio con Ubuntu 24.04 LTS, una dirección IPv4 pública y un dominio, por ejemplo langfuse.example.com. En Ubuntu 22.04, los comandos son casi idénticos. Realiza la configuración inicial mediante la consola del proveedor o SSH como usuario root y, después, desactiva el trabajo permanente como root.

Creación del administrador y acceso SSH

En el ordenador local, crea una clave si aún no tienes una. Utiliza el algoritmo moderno Ed25519 y protege la clave con una frase de contraseña.

ssh-keygen -t ed25519 -a 100 -C "admin@langfuse"

Copia la clave pública al servidor e inicia sesión como root. Sustituye la dirección IP por la del VPS.

ssh-copy-id [email protected]
ssh [email protected]

Crea un usuario independiente, añádelo al grupo sudo y prepara el directorio SSH.

adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
cp /root/.ssh/authorized_keys /home/deploy/.ssh/authorized_keys
chown deploy:deploy /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keys

Abre una segunda sesión SSH y comprueba que el usuario inicia sesión con la clave. No cierres la sesión root hasta que termine la comprobación.

ssh [email protected]
sudo whoami

Actualización del sistema y herramientas básicas

Actualiza los paquetes a su estado actual. Tras actualizar el kernel, reinicia el servidor en un momento conveniente.

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl gnupg ufw fail2ban unattended-upgrades \
  jq vim htop cron rsync

Comprueba si es necesario reiniciar.

test -f /var/run/reboot-required && echo "Reboot required"
sudo reboot

Firewall y Fail2ban

SSH, HTTP y HTTPS deben estar disponibles en el servidor. No expongas PostgreSQL, Redis ni ClickHouse a Internet: solo estarán disponibles para los contenedores de la red interna de Docker.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Fail2ban limitará los intentos de fuerza bruta de contraseñas SSH y las reconexiones maliciosas. Crea una configuración local sin editar directamente el archivo del paquete.

sudo tee /etc/fail2ban/jail.d/sshd.local > /dev/null <<'EOF'
[sshd]
enabled = true
maxretry = 5
findtime = 10m
bantime = 1h
EOF

sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

Después de confirmar el acceso con clave, desactiva el inicio de sesión de root y la autenticación por contraseña. Esto reduce la superficie de ataque, pero primero asegúrate de que tu clave SSH funciona.

sudo tee /etc/ssh/sshd_config.d/99-hardening.conf > /dev/null <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
EOF

sudo sshd -t && sudo systemctl reload ssh

Activa también la instalación automática de actualizaciones de seguridad. Aun así, las imágenes de Docker deberán actualizarse por separado, pero las vulnerabilidades del sistema operativo base se corregirán sin intervención manual.

sudo dpkg-reconfigure --priority=low unattended-upgrades

Instalación del software, paso a paso

Este esquema utiliza Docker Engine 28.x o posterior, Docker Compose v2, Langfuse rama v3, PostgreSQL 16, ClickHouse 24.8 LTS y Redis 7.2. Las versiones de los contenedores deben fijarse antes de una actualización de producción: la etiqueta latest puede provocar una migración inesperada del esquema o incompatibilidades.

Instalación de Docker Engine y Compose

Añada el repositorio oficial de Docker para Ubuntu. El comando instala Docker Engine, CLI, Buildx y el plugin de Compose.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Permita al usuario deploy ejecutar Docker sin sudo. La pertenencia al grupo Docker otorga de hecho capacidades administrativas en el servidor, por lo que añada únicamente usuarios de confianza.

sudo usermod -aG docker deploy
newgrp docker
docker version
docker compose version

Creación del directorio de trabajo

Mantenga el archivo Compose, las variables de entorno, el Caddyfile y los scripts juntos, en un directorio accesible para el usuario de despliegue. Los datos de las bases de datos estarán en Docker volumes.

sudo install -d -m 750 -o deploy -g deploy /opt/langfuse
cd /opt/langfuse
mkdir -p caddy backup scripts
touch .env
chmod 600 .env

Generación de secretos criptográficos

Langfuse utiliza secretos independientes para sesiones, sal y cifrado. No use ejemplos cortos de la documentación ni reutilice un mismo secreto para todas las variables.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -base64 48
openssl rand -base64 32

Guarde los cuatro resultados: los necesitará en .env. Para las contraseñas de PostgreSQL, Redis y ClickHouse, cree cadenas aleatorias independientes.

openssl rand -base64 32
openssl rand -base64 32
openssl rand -base64 32

Verificación del dominio antes del inicio

Cree un registro DNS de tipo A para langfuse.example.com, apuntándolo a la IPv4 pública del servidor. Caddy podrá obtener un certificado solo si el puerto 80 es accesible desde Internet y el DNS ya apunta a este servidor.

dig +short A langfuse.example.com
curl -4 ifconfig.me

Ambas direcciones deben coincidir. Si utiliza Cloudflare u otro DNS con proxy, en el primer inicio es más sencillo desactivar temporalmente el modo proxy o asegurarse de que el HTTP challenge no esté bloqueado.

Obtención de imágenes y diagnóstico inicial

Tras crear la configuración de la siguiente sección, Docker descargará las imágenes necesarias. Este comando las descarga previamente y permite ver errores de red o de acceso al registry antes del inicio.

cd /opt/langfuse
docker compose pull
docker compose config > /tmp/langfuse-rendered-compose.yml
docker compose config --quiet

Configuración de Langfuse, HTTPS y verificación

A continuación se muestra una configuración compacta de nodo único. Es adecuada para comenzar y no publica los puertos de PostgreSQL, ClickHouse ni Redis. Solo Caddy se expone a la red externa en los puertos 80 y 443.

Archivo de variables de entorno

Abra /opt/langfuse/.env y reemplace todos los valores de ejemplo por valores únicos. La dirección NEXTAUTH_URL debe coincidir exactamente con la URL pública, incluido https.

cd /opt/langfuse
nano .env

LANGFUSE_DOMAIN=langfuse.example.com

POSTGRES_DB=langfuse
POSTGRES_USER=langfuse
POSTGRES_PASSWORD=REPLACE_WITH_RANDOM_POSTGRES_PASSWORD

CLICKHOUSE_DB=default
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=REPLACE_WITH_RANDOM_CLICKHOUSE_PASSWORD

REDIS_PASSWORD=REPLACE_WITH_RANDOM_REDIS_PASSWORD

NEXTAUTH_URL=https://langfuse.example.com
NEXTAUTH_SECRET=REPLACE_WITH_RANDOM_BASE64_SECRET
SALT=REPLACE_WITH_RANDOM_HEX_SALT
ENCRYPTION_KEY=REPLACE_WITH_RANDOM_BASE64_KEY

DATABASE_URL=postgresql://langfuse:REPLACE_WITH_RANDOM_POSTGRES_PASSWORD@postgres:5432/langfuse
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=REPLACE_WITH_RANDOM_CLICKHOUSE_PASSWORD
REDIS_CONNECTION_STRING=redis://:REPLACE_WITH_RANDOM_REDIS_PASSWORD@redis:6379

TELEMETRY_ENABLED=false

El archivo contiene contraseñas, por lo que no lo añada a Git, no lo envíe en tickets ni lo incluya en registros de CI. Verifique los permisos de acceso.

chmod 600 /opt/langfuse/.env
ls -l /opt/langfuse/.env

Docker Compose

Cree el archivo /opt/langfuse/docker-compose.yml. Para Langfuse se fija la etiqueta de la rama principal 3; antes de una actualización planificada, reemplácela por una etiqueta patch específica y probada del registry oficial. El contenedor worker procesa tareas en segundo plano y debe ejecutarse de forma permanente.

cd /opt/langfuse
nano docker-compose.yml

services:
  postgres:
    image: postgres:16.6-bookworm
    restart: unless-stopped
    env_file: .env
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 10

  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    restart: unless-stopped
    env_file: .env
    environment:
      CLICKHOUSE_DB: ${CLICKHOUSE_DB}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    healthcheck:
      test: ["CMD-SHELL", "clickhouse-client --query 'SELECT 1'"]
      interval: 15s
      timeout: 10s
      retries: 10

  redis:
    image: redis:7.2-alpine
    restart: unless-stopped
    env_file: .env
    command: >
      redis-server --appendonly yes
      --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli -a \"${REDIS_PASSWORD}\" ping | grep PONG"]
      interval: 10s
      timeout: 5s
      retries: 10

  langfuse-web:
    image: ghcr.io/langfuse/langfuse:3
    restart: unless-stopped
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      NODE_ENV: production
      NEXTAUTH_URL: ${NEXTAUTH_URL}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      SALT: ${SALT}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
      DATABASE_URL: ${DATABASE_URL}
      CLICKHOUSE_URL: ${CLICKHOUSE_URL}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      REDIS_CONNECTION_STRING: ${REDIS_CONNECTION_STRING}
      TELEMETRY_ENABLED: ${TELEMETRY_ENABLED}
    expose:
      - "3000"

  langfuse-worker:
    image: ghcr.io/langfuse/langfuse:3
    restart: unless-stopped
    command: worker
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      NODE_ENV: production
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      SALT: ${SALT}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
      DATABASE_URL: ${DATABASE_URL}
      CLICKHOUSE_URL: ${CLICKHOUSE_URL}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      REDIS_CONNECTION_STRING: ${REDIS_CONNECTION_STRING}
      TELEMETRY_ENABLED: ${TELEMETRY_ENABLED}

  caddy:
    image: caddy:2.8-alpine
    restart: unless-stopped
    depends_on:
      - langfuse-web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  postgres_data:
  clickhouse_data:
  redis_data:
  caddy_data:
  caddy_config:

En algunas versiones menores de Langfuse, el conjunto de parámetros y el método de inicio del worker pueden cambiar. Antes de actualizar, consulte la sección de self-hosting de la documentación oficial de Langfuse y la salida de docker compose logs langfuse-web. No mezcle imágenes nuevas con un esquema antiguo arbitrario de variables de entorno.

Configuración de Caddy y TLS

Caddy obtiene y renueva automáticamente el certificado TLS de Let's Encrypt. Cree el Caddyfile; el correo es necesario para que la autoridad de certificación envíe notificaciones sobre problemas con el certificado.

cd /opt/langfuse
nano caddy/Caddyfile

{
    email [email protected]
}

langfuse.example.com {
    encode zstd gzip

    reverse_proxy langfuse-web:3000 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }

    log {
        output stdout
        format json
    }
}

Inicie la pila en segundo plano. El primer inicio puede tardar varios minutos: PostgreSQL crea el clúster, ClickHouse levanta las tablas y Langfuse aplica las migraciones.

cd /opt/langfuse
docker compose up -d
docker compose ps
docker compose logs --tail=100 langfuse-web

Verificación de disponibilidad

Verifique los contenedores y HTTPS desde el propio servidor. Un código de respuesta 200, 302 o 307 en la URL raíz normalmente indica que la interfaz está disponible; la ruta concreta del healthcheck depende de la versión de Langfuse.

docker compose ps
curl -I http://127.0.0.1
curl -I https://langfuse.example.com
docker compose logs --tail=100 caddy

Abra https://langfuse.example.com en el navegador, cree el primer usuario y la organización. Después cree un proyecto, por ejemplo production, y genere en su configuración una public key y una secret key. La secret key se muestra de forma limitada: guárdela en el gestor de secretos de la aplicación.

Prueba rápida desde Python

En la máquina donde se ejecuta su aplicación de IA, instale el SDK actual de Python de Langfuse. En producción, proporcione las claves mediante variables de entorno de CI/CD, Docker secrets o un almacén de secretos, no mediante el archivo fuente.

python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade langfuse openai

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

from langfuse import Langfuse

langfuse = Langfuse()

trace = langfuse.trace(
    name="manual-cost-test",
    user_id="demo-user",
    metadata={"environment": "test"}
)

generation = trace.generation(
    name="demo-generation",
    model="gpt-4o-mini",
    model_parameters={"temperature": 0.2},
    input=[{"role": "user", "content": "Скажи привет одним словом"}],
)

generation.end(
    output="Привет!",
    usage={"input": 12, "output": 3, "total": 15}
)

langfuse.flush()

Abra la sección Traces de la interfaz. Debe aparecer el rastreo manual-cost-test con generation y usage. Para el cálculo automático de costes, el nombre del modelo debe coincidir con el modelo configurado en las model definitions de Langfuse. Si utiliza un proxy, un deployment de Azure o un modelo local, cree su propio modelo e indique el precio por millón de tokens de entrada y salida.

Copias de seguridad y mantenimiento

Una instantánea de VPS es útil, pero no sustituye una copia de seguridad independiente. Puede crearse después de un error, depender de un único centro de datos o no permitir restaurar rápidamente una base de datos concreta. La estrategia mínima: un volcado lógico diario de PostgreSQL, una copia de seguridad de ClickHouse, una copia de .env, Caddyfile y los datos del almacenamiento de objetos, si está conectado.

Qué debe guardarse exactamente

Instalación de restic

Restic cifra las copias de seguridad en el lado del servidor y puede trabajar con almacenamiento compatible con S3, SFTP o una máquina independiente. No guarde la única copia de seguridad en el mismo VPS donde se ejecuta Langfuse.

sudo apt install -y restic
sudo install -d -m 700 -o deploy -g deploy /opt/langfuse/backup
nano /opt/langfuse/backup/restic.env
chmod 600 /opt/langfuse/backup/restic.env

Ejemplo de archivo para un bucket compatible con S3. Sustituya el endpoint, bucket y las claves de acceso por los suyos. La contraseña del repositorio debe ser distinta de todas las contraseñas de Langfuse.

RESTIC_REPOSITORY=s3:https://s3.example.net/langfuse-backups
RESTIC_PASSWORD=REPLACE_WITH_LONG_UNIQUE_BACKUP_PASSWORD
AWS_ACCESS_KEY_ID=REPLACE_WITH_S3_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=REPLACE_WITH_S3_SECRET_KEY

Inicialice un repositorio vacío una vez.

set -a
. /opt/langfuse/backup/restic.env
set +a
restic init

Script de copia de seguridad diaria

El script crea un volcado de PostgreSQL, utiliza la copia de seguridad integrada de ClickHouse mediante una copia de archivos tras una breve detención del servicio y envía el resultado a restic. Para bases de datos de production grandes, es mejor configurar ClickHouse Keeper y los destinos de backup estándar, pero para una instancia single-node esta opción es clara y adecuada para restauraciones periódicas.

nano /opt/langfuse/scripts/backup-langfuse.sh
chmod 700 /opt/langfuse/scripts/backup-langfuse.sh

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="/opt/langfuse"
BACKUP_DIR="${APP_DIR}/backup/staging"
DATE="$(date +%F-%H%M%S)"

mkdir -p "${BACKUP_DIR}"
cd "${APP_DIR}"

set -a
. "${APP_DIR}/.env"
. "${APP_DIR}/backup/restic.env"
set +a

docker compose exec -T postgres \
  pg_dump -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
  -Fc > "${BACKUP_DIR}/postgres-${DATE}.dump"

docker compose stop clickhouse
docker run --rm \
  -v langfuse_clickhouse_data:/source:ro \
  -v "${BACKUP_DIR}:/backup" \
  alpine:3.20 \
  sh -c "tar -czf /backup/clickhouse-${DATE}.tar.gz -C /source ."
docker compose start clickhouse

tar -czf "${BACKUP_DIR}/config-${DATE}.tar.gz" \
  "${APP_DIR}/.env" \
  "${APP_DIR}/docker-compose.yml" \
  "${APP_DIR}/caddy/Caddyfile"

restic backup "${BACKUP_DIR}"
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

rm -f "${BACKUP_DIR}"/

/opt/langfuse/scripts/backup-langfuse.sh
set -a && . /opt/langfuse/backup/restic.env && set +a
restic snapshots
restic check

crontab -e

20 3    /opt/langfuse/scripts/backup-langfuse.sh >> /opt/langfuse/backup/backup.log 2>&1

Actualizaciones y supervisión del estado

Para un servidor único, la actualización de Langfuse es una maintenance window, no un rolling update completo: la interfaz web y la ingestion pueden no estar disponibles brevemente. Primero cree una copia de seguridad, lea las release notes, registre las versiones actuales y solo entonces actualice las imágenes.

cd /opt/langfuse
docker compose images
/opt/langfuse/scripts/backup-langfuse.sh
docker compose pull
docker compose up -d
docker compose logs --tail=150 langfuse-web
docker compose ps

No ejecute sin comprobar el comando docker system prune -a en un servidor de production: puede eliminar imágenes necesarias y dificultar la reversión. Después de la actualización, cree una traza de prueba, compruebe el acceso a la interfaz y revise los errores de los contenedores.

docker compose logs --since=15m | grep -iE "error|fatal|exception" || true
df -h
docker stats --no-stream

Solución de problemas y FAQ

¿Por qué Caddy no obtiene un certificado y aparece un ACME error en los registros?

Primero compruebe DNS: el comando dig +short A langfuse.example.com debe devolver la IP de su servidor. Después asegúrese de que UFW permite los puertos TCP 80 y 443 y de que otro servidor web no ha ocupado esos puertos: sudo ss -ltnp '( sport = :80 or sport = :443 )'. Si está activado un proxy CDN, cambie temporalmente el registro a DNS-only. Compruebe también que el dominio no tenga un registro AAAA que apunte a un servidor IPv6 inaccesible.

Langfuse se abre, pero tras iniciar sesión se produce un redirect infinito o un error de sesión. ¿Qué hacer?

La causa más frecuente es un NEXTAUTH_URL incorrecto o un NEXTAUTH_SECRET modificado. La URL debe ser una dirección pública con https://, sin rutas adicionales ni localhost. Compruebe la variable con el comando docker compose exec langfuse-web printenv | grep NEXTAUTH y después reinicie el contenedor. No cambie NEXTAUTH_SECRET sin necesidad: esto finalizará las sesiones de usuario existentes.

¿Por qué no hay trazas en la interfaz después de enviar eventos desde la aplicación?

Compruebe tres elementos: public key, secret key y LANGFUSE_BASE_URL. Las claves deben pertenecer al proyecto correcto y la base URL debe apuntar a su dominio HTTPS. Después revise los registros de worker y web: docker compose logs --tail=100 langfuse-worker. Si la aplicación está en una red cerrada, compruebe el acceso saliente al dominio de Langfuse. Para diagnosticarlo, envíe una trace de prueba mínima del ejemplo anterior y llame a langfuse.flush() antes de finalizar el proceso.

El coste de las solicitudes se muestra como cero o como un valor vacío. ¿Por qué?

Langfuse puede mostrar usage, pero no calcular el precio si el nombre del modelo es desconocido, no se envían tokens o el modelo se invoca mediante un deployment name no estándar. Transmita los campos input, output y usage desde la respuesta del proveedor. Después abra la configuración de modelos del proyecto y añada la definición de su modelo con la tarifa por millón de input/output tokens. Para Azure OpenAI suele ser útil asociar manualmente el deployment name con el modelo real.

El contenedor de ClickHouse se reinicia constantemente o el servidor se queda sin memoria. ¿Cómo solucionarlo?

Compruebe la causa con docker compose logs clickhouse y dmesg -T | grep -i oom. Un mensaje OOM significa que el kernel finalizó el proceso debido a la falta de RAM. Para un funcionamiento estable, aumente la memoria a 8 GB, reduzca la carga paralela y asegúrese de que haya suficiente espacio libre en disco. El swap temporal es aceptable como medida de emergencia, pero no sustituye la RAM: ClickHouse en swap se vuelve considerablemente más lento.

¿Qué configuración de VPS es mínimamente adecuada?

Para un entorno de pruebas personal, bastan 2 vCPU, 4 GB de RAM y 60 GB de SSD/NVMe, si no almacena muchos eventos ni ejecuta varias aplicaciones en paralelo. Para un equipo real, el mínimo razonable es 4 vCPU, 8 GB de RAM y 100 GB de NVMe. Supervise docker stats, free -h y df -h durante la primera semana: el crecimiento de ClickHouse-data mostrará la necesidad real de disco.

¿Qué elegir: VPS o dedicated para esta tarea?

Para empezar, casi siempre basta con un VPS: es más económico, escala más rápido y permite aumentar rápidamente la RAM o el disco. Se necesita dedicated con un flujo muy grande de eventos de telemetry, retención prolongada, consultas analíticas pesadas o requisitos de aislamiento de hardware. Una buena etapa intermedia es mantener la aplicación web en un VPS y mover PostgreSQL y ClickHouse a nodos gestionados o dedicados independientes. Esto es más sencillo que comprar prematuramente un servidor grande.

¿Se pueden eliminar trazas antiguas y reducir el uso de disco?

Sí, pero primero defina una retention policy: por ejemplo, 30 días para trazas de production sin procesar y 90 días para analítica agregada. Es mejor eliminar mediante los mecanismos de retention estándar y la documentación de la versión actual de Langfuse, en lugar de eliminar manualmente archivos del Docker volume. La eliminación manual de directorios de ClickHouse dañará los metadatos de las tablas. Después de configurar retention, controle el tamaño de los volumes con el comando docker system df -v y la disponibilidad de espacio libre en el host.

¿Cómo restaurarse desde una copia de seguridad?

Implemente versiones compatibles de los contenedores en un nuevo servidor, restaure .env y la configuración de Compose, y luego detenga los servicios. El volcado de PostgreSQL en formato custom se restaura mediante pg_restore dentro del contenedor. El archivo de ClickHouse debe descomprimirse en un volume vacío con el contenedor detenido y luego iniciar ClickHouse. Antes de cambiar DNS, compruebe obligatoriamente el acceso, la lista de proyectos y varias trazas en un dominio temporal o mediante el archivo hosts.

Conclusiones y próximos pasos

Ahora dispone de Langfuse self-hosted con HTTPS, bases de datos internas aisladas, trazado de llamadas LLM y una base para calcular el coste de los tokens. Esta instalación ayuda a encontrar prompts costosos, cadenas lentas de agentes y errores de integración antes de que se conviertan en un problema para los usuarios.

1. Conecte el SDK a la aplicación de production y comience trazando un escenario de usuario crítico.
2. Configure los modelos y los precios; después, cree un informe periódico de costes por usuario, proyecto o endpoint.
3. Cuando aumente la carga, traslade ClickHouse y PostgreSQL a nodos independientes, añada supervisión del disco, la memoria y el éxito de las copias de seguridad.