Como autohospedar Superlog en tu propio servidor
Aprende a desplegar el stack de Superlog con Docker Compose. Analiza el consumo real de Postgres y ClickHouse antes de implementar el triaje de logs basado en IA.
Qué instala realmente el autohospedaje de Superlog
Para autohospedar Superlog, clone el repositorio, inicie Postgres, ClickHouse y un colector OpenTelemetry con Docker Compose, ejecute una migración de base de datos y luego inicie cuatro servicios Node desde el código fuente. Sus aplicaciones envían trazas, registros y métricas mediante OTLP (protocolo OpenTelemetry) a un puerto de entrada, Superlog los identifica, agrupa los repetidos en una sola incidencia y el agente ejecutor de la comunidad predeterminado registra un resumen de la incidencia local. La instalación lleva una tarde. La huella de memoria y los límites reales son los puntos que debe leer antes de comenzar.
Superlog tiene licencia Apache 2.0 y se encuentra en github.com/superloglabs/superlog. A fecha de 13 de octubre de 2026, cuenta con alrededor de 1.5k estrellas, aproximadamente 490 commits en main y ninguna etiqueta de versión (release tags). Fije un commit usted mismo en lugar de ejecutar el que haya resultado ser main la mañana en que realizó el clonado.
Qué responde Superlog que Uptime Kuma y Langfuse no responden
Las herramientas de monitorización autohospedadas parecen intercambiables desde fuera. No lo son, y ejecutar la incorrecta le cuesta un servidor sin obtener beneficio alguno.
- Uptime Kuma sondea sus endpoints desde el exterior y responde a una pregunta: ¿está activo?
- Zabbix vigila hosts y servicios en Ubuntu 24.04, con CPU, memoria, disco y estado del servicio frente a los umbrales que usted defina.
- Langfuse rastrea llamadas a LLM, registrando el prompt, el modelo, los tokens, la latencia y el coste de cada una.
- Superlog toma la telemetría que sus servicios ordinarios ya emiten y convierte los fallos repetidos en incidentes.
Superlog se encarga de una pregunta distinta: algo se rompió, qué se rompió y por qué. No tiene opinión sobre las llamadas a LLM y no le sondea desde el exterior. Ingiere OTLP desde el código de su aplicación normal y coloca un agente en el paso de triaje, que es la primera revisión que un humano de guardia haría de todos modos.
La distinción que importa para el presupuesto de un VPS es el almacenamiento. Superlog utiliza un almacén de columnas, porque la telemetría se escribe una vez y luego se consulta por rango de tiempo a través de millones de filas. Para eso sirve ClickHouse y para eso no sirve Postgres. Postgres sigue en la pila, manteniendo los datos relacionales pequeños: proyectos, usuarios, incidentes y claves de ingesta.
¿Qué inicia realmente docker compose up -d?
Tres contenedores, y ninguno de ellos es Superlog. Esto sorprende a quienes esperan una instalación con un solo comando.
postgres:16, publicado en el puerto 5434 del hostclickhouse/clickhouse-server:26.1, en el puerto 8123 para HTTP y en el 9000 para el protocolo nativootel/opentelemetry-collector-contrib:0.150.1, en el puerto 4317 para gRPC y en el 4318 para OTLP sobre HTTP
Las aplicaciones de Superlog se ejecutan en el host desde el código fuente y las inicia pnpm dev. No hay un archivo de Compose para producción en el repositorio a fecha de 13 de octubre de 2026, por lo que una instalación de larga duración requiere sus propias unidades de systemd o los Dockerfiles de cada aplicación incluidos en el árbol. Las aplicaciones api, worker y proxy tienen cada una un script start para envolver una unidad. La aplicación web no tiene ninguno: es una aplicación de Vite, por lo que se compila con su script build y se sirve el resultado como archivos estáticos desde nginx o Caddy, o se ejecuta su script preview, que es vite preview.
Tenga presente la ruta que sigue un span, porque cada fallo descrito a continuación interrumpe uno de sus saltos. La aplicación envía OTLP mediante POST al proxy de ingesta de Superlog. El proxy autentica la solicitud con la clave de ingesta, le asigna el ID del proyecto y la reenvía al collector. El collector elimina cualquier atributo superlog.* que el cliente haya intentado establecer, añade superlog.project_id a partir de la cabecera proporcionada por el proxy, agrupa los datos y los escribe en ClickHouse. La aplicación web y la API leen después la telemetría desde ClickHouse y obtienen todo lo demás de Postgres.
La eliminación de esos atributos es un control real de la tenencia múltiple, no un elemento decorativo. Sin ella, cualquiera que tenga una clave de ingesta válida podría establecer superlog.project_id por su cuenta y escribir datos en otro proyecto.
¿Qué tamaño debe tener el VPS?
Planifique para 4 vCPU, 8 GB de RAM y 40 GB de SSD para una instalación de nodo único con un volumen de ingesta bajo. Ese es un suelo de planificación, no una medición, así que trátelo como un tamaño inicial y compruébelo con su propio tráfico.
La memoria se destina a cuatro lugares. ClickHouse está diseñado para máquinas con mucha RAM y sus valores predeterminados asumen eso. Postgres 16 es modesto aquí, ya que contiene metadatos en lugar de telemetría. El recolector también es modesto. Los cuatro procesos de Node incluyen un servidor de desarrollo Vite más tres procesos tsx watch; mida su uso de memoria en su propio equipo.
El disco es el problema más silencioso. pnpm install en este monorepo descarga el AWS SDK, un cliente de ClickHouse, el OpenTelemetry SDK y una cadena de herramientas de React antes de que haya ingerido un solo span. ClickHouse luego crece con su tráfico. Mida ambos:
df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"La carga que causa problemas es el pico: un despliegue defectuoso que produce miles de errores idénticos por minuto. La creación de huellas digitales (fingerprinting) colapsa esos errores en un solo incidente para el lector, pero ClickHouse sigue escribiendo cada fila por debajo.
La retención es algo que usted debe configurar. El exportador de ClickHouse del recolector crea las tablas, otel_traces, otel_logs y una tabla por tipo de métrica, y solo aplica un tiempo de vida (TTL) si la configuración en infra/collector/config.yaml establece uno. Nada expira por sí solo, por lo que un mes con mucha actividad se convierte en un disco lleno a menos que lo planifique.
Instalar desde un commit fijado
git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'git tag -l que no se imprima nada es el resultado esperado a fecha de 13 de octubre de 2026. Elija el commit que probó y manténgase en él:
git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1eA continuación, la cadena de herramientas:
node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -vpackage.json declara engines.node como >=20.0.0 y packageManager como pnpm@9.12.0. Una versión de Node incompatible no detiene la instalación automáticamente: la aplicación de la versión del motor depende de la configuración, y pnpm 9.12.0 tiene una ruta de advertencia cuando engineStrict está desactivado. El paquete nodejs en el repositorio de Ubuntu 24.04 es anterior a la versión 20, así que instale Node 20 o superior desde NodeSource o mediante nvm. El repositorio incluye un .nvmrc, por lo que nvm use selecciona la versión prevista si utiliza nvm.
pnpm install
docker compose up -d
docker compose psEspere a las comprobaciones de estado en lugar de confiar en que up -d significa que está listo. Tanto Postgres como ClickHouse declaran una en el archivo compose:
curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgresClickHouse responde Ok. y pg_isready responde accepting connections. Un error de conexión rechazada (connection refused) en 8123 significa que el contenedor aún se está iniciando o ha terminado. docker compose logs clickhouse muestra cuál es el caso, y docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled informa de true cuando el kernel lo ha finalizado por falta de memoria, lo que indica que el servidor es demasiado pequeño en lugar de un error en su configuración.
Luego, la migración y las aplicaciones:
pnpm --filter @superlog/db db:migrate
pnpm devTenga en cuenta el puerto: 5434, no 5432. El archivo compose publica Postgres en 5434 para que no colisione con un Postgres ya instalado en el host, y los archivos .env.example de la aplicación coinciden, con DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Si apunta la migración al puerto 5432 en un servidor que ya ejecuta Postgres, obtendrá una conexión rechazada o, peor aún, una migración aplicada a la base de datos incorrecta.
pnpm dev ejecuta turbo run dev, que inicia el script dev de cada aplicación a través de Turborepo, incluyendo api, web, worker y proxy, con su salida mezclada en una sola terminal. El archivo Procfile del repositorio enumera los mismos cuatro procesos y redirige la salida de cada uno a tmp/logs/. Inícielo con un ejecutor de Procfile como overmind o foreman en lugar de pnpm dev si desea que tail -f tmp/logs/proxy.log sea donde monitoriza la ingesta. El archivo README sitúa la aplicación web en http://localhost:5173, la API en http://localhost:4100 y la ingesta OTLP en http://localhost:4101.
Confirme qué se ha vinculado realmente antes de apuntar algo hacia ello:
ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/healthEsto es importante más adelante. El proxy lee su propio puerto de la variable de entorno PORT y utiliza 4000 por defecto cuando PORT no está definido, y el apps/proxy/.env.example que carga también establece PORT=4000, aunque el README enumera la ingesta en 4101 (ambos verificados el 13 de octubre de 2026). Utilice el puerto que muestre ss. Los ejemplos a continuación utilizan 4101, así que cámbielo por 4000 si ese es el que se vinculó. Una unidad de systemd que usted escriba no establece nada a menos que incluya PORT en ella, por lo que un exportador dirigido al puerto 4101 contra un proxy que escucha en 4000 fallará con una conexión rechazada y no le dará ninguna otra pista.
Envíe un rastro, genere un error, observe un incidente
Cree un proyecto en la aplicación web y copie su clave de ingesta. La entrada autentica cada petición mediante esa clave, por lo que la telemetría enviada sin ella nunca llega a ClickHouse.
Apunte cualquier SDK de OpenTelemetry a la entrada utilizando las variables de entorno estándar:
export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'La entrada lee la clave desde la cabecera x-api-key y también acepta authorization: bearer YOUR_INGEST_KEY si su exportador es más fácil de configurar de esa manera. Atiende las tres rutas OTLP estándar, /v1/traces, /v1/logs y /v1/metrics, además de /health.
Vale la pena mencionar una trampa. OTEL_EXPORTER_OTLP_ENDPOINT es una URL base y el SDK le añade la ruta de la señal. Las variables específicas de señal, como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, se utilizan exactamente como están escritas, sin añadir ninguna ruta. Si configura la variable específica de señal en http://127.0.0.1:4101, cada exportación se enviará a /, lo cual no es una ruta válida; por lo tanto, no llega nada y el SDK registra un fallo de exportación mientras su aplicación parece funcionar correctamente.
Para un servicio Node, la ruta sin código es suficiente para probar la canalización:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.jsAhora, provoque un fallo a propósito. Cualquier ruta que genere una excepción servirá:
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boomCompruebe los saltos en orden, ya que la primera brecha le indicará cuál ha fallado:
tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'Un recuento ascendente en otel_traces con una aplicación web vacía indica una discrepancia de proyecto, así que verifique a qué proyecto pertenece la clave de ingesta. Un recuento plano con actividad en el registro del proxy apunta al colector o a la escritura en ClickHouse, por lo que debe leer docker compose logs collector. La ausencia total de actividad en el registro del proxy significa que el exportador nunca llegó a la entrada: puerto incorrecto, ruta incorrecta o clave rechazada.
En la aplicación web, esos fallos repetidos llegan como un único incidente en lugar de una fila por petición. Superlog crea huellas digitales de las señales entrantes y agrupa las que coinciden, lo cual marca la diferencia entre una bandeja de entrada con 4,000 errores idénticos y una página con uno solo. El ejecutor del agente comunitario predeterminado registra entonces un resumen de incidente local para ese grupo.
Una investigación respaldada por un modelo requiere un proveedor de modelos y un ejecutor de agente compatible configurado; el ejecutor comunitario predeterminado registra un resumen local. Tome esos nombres de variables del archivo .env.example dentro de cada directorio de aplicación de la confirmación (commit) que fijó, en lugar de cualquier documentación externa, ya que cambian con main. Lo mismo se aplica a las integraciones de GitHub y Sentry, que llevan sus propios documentos de configuración en docs/github-app-setup.md y docs/sentry-app-setup.md, con las cargas útiles de webhook documentadas en docs/webhooks.md.
Mantenga la ingesta privada y el agente en modo de solo lectura
Docker publica los puertos de los contenedores en 0.0.0.0 de forma predeterminada, y esos puertos publicados omiten ufw. Docker enruta el tráfico de los contenedores en la tabla nat, por lo que un paquete destinado a un puerto publicado se desvía antes de llegar a las cadenas INPUT y OUTPUT donde residen las reglas de ufw, y ufw nunca interviene. En un VPS con una IP pública, el archivo compose tal como se distribuye expone ClickHouse HTTP en 8123 y Postgres en 5434, donde internet puede acceder a ellos. Las credenciales en ese archivo son valores predeterminados de desarrollo: el usuario de ClickHouse default con contraseña vacía, y Postgres con postgres tanto para el usuario como para la contraseña.
Enlácelos al loopback. Cada puerto publicado en el archivo compose toma su lado del host de una variable de entorno, por lo que un .env en la raíz del repositorio es suficiente:
POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318Verifique el resultado antes de confiar en él y luego vuelva a crear los contenedores:
docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'docker compose config imprime el archivo resuelto, por lo que puede leer 127.0.0.1:5434:5432 en lugar de adivinar. ss debería mostrar entonces 127.0.0.1:5434 y nunca 0.0.0.0:5434. Simplemente redeclarar ports en un archivo de anulación de Compose mantiene ambos enlaces cuando la IP del host difiere; Compose 2.24.4 y versiones posteriores admiten ports: !override para reemplazar la lista.
La ingesta requiere el mismo cuidado. Su clave de ingesta viaja en una cabecera, por lo que necesita TLS (transport layer security) delante: termine TLS en nginx o Caddy antes del proxy, o mantenga la ingesta dentro de una red privada o un túnel WireGuard. La aplicación web en 5173 es un servidor de desarrollo Vite y no debe estar expuesta a internet bajo ninguna circunstancia.
Luego, el agente en sí. La propuesta de valor de Superlog es que el agente investiga y propone una solución, y la palabra importante es propone. Manténgalo en modo de solo lectura frente a producción hasta que lo haya visto trabajar en algunos incidentes reales. Una GitHub App de solo lectura no puede enviar una rama de corrección ni abrir pull requests: la guía de configuración requiere permisos de escritura en Contents y Pull requests para ese flujo de trabajo, además de permisos de escritura en Issues para los comentarios. Un agente que lee telemetría y escribe un parche es útil. Un agente que puede reiniciar sus servicios representa un nivel de riesgo diferente, y esa debe ser una decisión que usted tome deliberadamente en lugar de un valor predeterminado que hereda. El coste merece la misma atención cuando configura un ejecutor respaldado por un modelo: presupuesto para el gasto del agente en un VPS antes de dirigirlo a un sistema de producción con mucho ruido, y mantenga un registro de lo que realmente hizo el agente para que una pull request inesperada tenga una pista de auditoría detrás.
Fallos que encontrará y las cadenas que los identifican
ERR_PNPM_UNSUPPORTED_ENGINEdurantepnpm installsignifica que un requisito del motor es incompatible. pnpm 9.12.0 verifica tanto los requisitos de Node como los de pnpm; lea las versiones solicitadas y actuales en el error, luego verifiquenode -vypnpm -v.ECONNREFUSED 127.0.0.1:5434durante la migración significa que la pila de compose no está activa, o queDATABASE_URLindica el puerto incorrecto.- Compruebe los reinicios de ClickHouse con
docker compose logs clickhouse, luego verifique en el contenedor queOOMKilledseatrue. - Un exportador que informa de éxito mientras la aplicación web permanece vacía suele significar que los datos fueron directamente al colector en el puerto 4318, lo cual omite el sellado del proyecto que realiza el proxy.
- Connection refused en el puerto 4101 suele significar que el proxy está escuchando en el 4000, el puerto al que recurre su código por defecto y el que establece su
.env.example. DefinaPORTexplícitamente en el archivo de unidad o en el.envde la aplicación. docker compose psmostrando0.0.0.0:8123significa que sus enlaces de loopback no están activos. Ejecutedocker compose configy lea los puertos resueltos.
Flawless, HyperProbe y el lugar de Superlog
Esta categoría es reciente y las herramientas difieren en cuanto a qué puede tocar el agente. El repositorio de Flawless presenta ahora CISRE, una plataforma de SRE (ingeniería de fiabilidad de sitios) basada en IA para Kubernetes e infraestructura en la nube, bajo la licencia PolyForm Noncommercial. HyperProbe coloca sondas dentro de un proceso en ejecución para capturar el estado de las variables y expone dicho estado a un asistente mediante MCP (protocolo de contexto de modelo); también documenta el autoalojamiento con Docker Compose y una clave de licencia.
Superlog se sitúa entre ambos. Controla la canalización de extremo a extremo, desde la ingesta de OTLP hasta el almacenamiento en ClickHouse, y coloca al agente en la fase de triaje en lugar de en la fase de corrección. Ese diseño es precisamente la razón por la cual su autoalojamiento es una decisión de infraestructura y no un contenedor que se pueda ignorar. Una vez que ejecuta Superlog, está ejecutando un almacén de columnas, y este requiere el mismo cuidado que cualquier otra base de datos de su propiedad.
FAQ
¿Cuánta memoria RAM necesita una instancia de Superlog autohospedada?
Planifique 8 GB de RAM, 4 vCPU y 40 GB de disco para un nodo único con un volumen de ingesta bajo. La pila incluye Postgres, ClickHouse, un colector OpenTelemetry y cuatro procesos Node; ClickHouse requiere margen de maniobra. Mida sus propias cifras con docker stats --no-stream y free -m en lugar de confiar en cualquier cifra publicada, incluida esta.
¿A qué puerto debo dirigir mi exportador OTLP?
Al proxy de ingesta de Superlog, que el README sitúa en http://localhost:4101. Este sirve /v1/traces, /v1/logs y /v1/metrics, y se autentica con la clave de ingesta de su proyecto tomada de la cabecera x-api-key o de una cabecera authorization: bearer. El puerto 4318 corresponde al colector OpenTelemetry subyacente; exportar directamente a él omite el proxy, que es el componente que añade el ID de su proyecto a los datos. El proxy utiliza el puerto 4000 por defecto cuando PORT no está definido, y su .env.example también establece 4000; por tanto, ejecute ss -lntp y confirme a qué puerto se ha vinculado antes de asumir que es el 4101.
¿Reemplaza Superlog a Uptime Kuma o Zabbix?
No. Uptime Kuma responde si un endpoint responde desde fuera de su red, y Zabbix supervisa las métricas de host y servicio frente a los umbrales que usted defina. Superlog consume los trazos, registros y métricas que emiten sus aplicaciones y agrupa los fallos repetidos en incidentes. Mantenga una sonda de tiempo de actividad externa junto a él, ya que una sonda que se ejecute en otro lugar seguirá informando cuando el equipo que aloja su canalización de telemetría sea el que ha fallado.
¿Puede el agente de Superlog modificar mis sistemas de producción?
Solo mediante los permisos que usted le conceda. El ejecutor comunitario predeterminado registra un resumen de incidentes local; otros entornos de ejecución de investigación dependen del ejecutor que usted configure. Mantenga las credenciales de producción limitadas a lectura; abrir solicitudes de extracción (pull requests) requiere permisos de escritura de GitHub independientes para ramas y solicitudes de extracción. Considere el acceso de escritura a producción como una decisión independiente y deliberada, ya que un agente capaz de reiniciar servicios supone un compromiso mucho mayor que un agente que solo lee telemetría y escribe un parche para su revisión.
¿Debo fijar un commit o seguir la rama main?
Fije un commit. A fecha de 13 de octubre de 2026, no había etiquetas de versión (release tags) en el repositorio. Registre el SHA que haya probado, despliegue esa versión y lea las diferencias (diff) antes de avanzar. git log --oneline <old-sha>..main es la revisión, y los archivos .env.example por aplicación son el primer lugar donde buscar variables nuevas requeridas tras cualquier actualización.