Superlog autoalojado: recursos, instalación y límites

Qué instala realmente Superlog cuando lo aloja usted mismo

Para alojar Superlog usted mismo, clone el repositorio, inicie Postgres, ClickHouse y un colector de OpenTelemetry con Docker Compose, ejecute una migración de base de datos y, después, inicie cuatro servicios de Node desde el código fuente. Sus aplicaciones envían trazas, registros y métricas OTLP (protocolo de OpenTelemetry) a un puerto de recepción. Superlog les calcula una huella, agrupa los elementos repetidos en un único incidente y un agente redacta el primer análisis de triaje. La instalación ocupa una tarde. Conviene leer sobre el consumo de recursos y las limitaciones reales antes de empezar.

Superlog usa la licencia Apache 2.0 y se encuentra en github.com/superloglabs/superlog. En agosto de 2026 tiene aproximadamente 1.2k estrellas, unos 460 commits en main y ningún tag de versión. Este último punto condiciona la instalación: git checkout v1.0.0 no tiene nada que se pueda descargar, por lo que debe fijar usted mismo un commit o ejecutar la versión de main que estuviera disponible la mañana en que clonó el repositorio.

Qué responde Superlog que Uptime Kuma y Langfuse no responden

Las herramientas de monitorización autoalojadas parecen intercambiables a primera vista. No lo son, y elegir la incorrecta consume recursos del servidor sin aportar ningún beneficio.

• Uptime Kuma comprueba sus endpoints desde el exterior y responde a una sola pregunta: ¿está disponible?
• Zabbix supervisa hosts y servicios en Ubuntu 24.04, junto con la CPU, la memoria, el disco y el estado de los servicios, comparándolos con los umbrales que defina.
• Langfuse registra las trazas de las llamadas a LLM, incluidos el prompt, el modelo, los tokens, la latencia y el coste de cada llamada.
• Superlog toma la telemetría que ya emiten sus servicios habituales y convierte los fallos repetidos en incidentes.

Superlog responde a otra pregunta: algo ha fallado, qué ha fallado y por qué. No gestiona llamadas a LLM ni realiza comprobaciones desde el exterior. Recibe datos OTLP del código normal de su aplicación y coloca un agente en el paso de triaje, que es la primera comprobación que haría una persona de guardia.

La diferencia importante para el presupuesto de un VPS es el almacenamiento. Uptime Kuma funciona sin problemas con 1 GB de RAM porque almacena unos pocos miles de resultados de comprobaciones. Superlog utiliza un almacén de columnas, porque la telemetría se escribe una vez y después se consulta por rangos temporales entre millones de filas. Para eso sirve ClickHouse y eso es lo que Postgres no hace. Postgres sigue formando parte de la pila y almacena los datos relacionales pequeños: proyectos, usuarios, incidentes y claves de ingesta.

¿Qué inicia realmente docker compose up -d?

Inicia 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 host
• clickhouse/clickhouse-server:26.1, en el puerto 8123 para HTTP y en el 9000 para el protocolo nativo
• otel/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. A fecha de agosto de 2026, el repositorio no incluye un archivo de Compose para producción. Por tanto, una instalación de larga duración requiere sus propias unidades de systemd para cada script start de aplicación, o los Dockerfiles de cada aplicación incluidos en el árbol.

Tenga presente la ruta que sigue un span, porque cada fallo descrito a continuación corresponde a una interrupción en uno de sus saltos. La aplicación envía OTLP al proxy de ingesta de Superlog. El proxy autentica la solicitud con la clave de ingesta, le asigna el identificador del proyecto y la reenvía al collector. El collector elimina los atributos 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 la telemetría desde ClickHouse y todos los demás datos desde Postgres.

La eliminación de esos atributos es un control real de la multitenencia, no un elemento decorativo. Sin ella, cualquiera que tuviera una clave de ingesta válida podría establecer superlog.project_id por su cuenta y escribir datos en el proyecto de otro usuario.

¿Qué tamaño necesita el VPS?

Planifique 4 vCPU, 8 GB de RAM y 40 GB de SSD para una instalación de un solo nodo con un volumen bajo de ingesta. Ese es un tamaño mínimo de planificación, no una medición. Úselo como punto de partida y compárelo con su propio tráfico.

La memoria se reparte entre cuatro componentes. ClickHouse está diseñado para máquinas con mucha RAM y sus valores predeterminados parten de esa suposición. Postgres 16 tiene un consumo moderado en este caso, porque almacena metadatos en lugar de telemetría. El collector también tiene un consumo moderado. Los cuatro procesos de Node no: un servidor de desarrollo de Vite y tres procesos de tsx watch consumen cientos de megabytes cada uno. Por eso pnpm dev en una máquina con 2 GB resulta problemático.

El disco es el problema menos evidente. 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 ingerir un solo span. Después, ClickHouse crece con el tráfico. Mida ambos aspectos:

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"

Con un volumen bajo, unos pocos servicios que envían unos cientos de spans por minuto, la máquina permanece inactiva y ClickHouse está desocupado la mayor parte del tiempo. La carga problemática aparece durante los picos: una implementación defectuosa puede generar miles de errores idénticos por minuto. El fingerprinting los agrupa en un solo incidente para el lector, pero ClickHouse sigue escribiendo cada fila internamente.

La retención la define usted. El exporter de ClickHouse del collector crea las tablas, otel_traces, otel_logs y una tabla para cada tipo de métrica. Sólo aplica un tiempo de vida si la configuración de infra/collector/config.yaml define uno. Nada caduca automáticamente. Por tanto, un mes con mucho tráfico puede llenar todo el disco si no lo planifica.

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 no mostrar nada es el resultado esperado en agosto de 2026. Elija el commit que haya probado y manténgase en él:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

A continuación, la cadena de herramientas:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json declara engines.node como >=20.0.0 y packageManager como pnpm@9.12.0. Si ejecuta la instalación con una versión anterior de Node, pnpm se detiene con ERR_PNPM_UNSUPPORTED_ENGINE e indica la versión que necesita. El paquete nodejs del repositorio de Ubuntu 24.04 es anterior a 20, así que instale Node 20 o una versión posterior desde NodeSource o mediante nvm. El repositorio incluye un .nvmrc, por lo que nvm use selecciona la versión prevista si tiene nvm.

pnpm install
docker compose up -d
docker compose ps

Espere a que finalicen las comprobaciones de estado en lugar de asumir que up -d significa que el servicio está listo. Postgres y ClickHouse declaran una comprobación en el archivo compose:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse responde en Ok. y pg_isready responde en accepting connections. Una conexión rechazada en 8123 significa que el contenedor todavía se está iniciando o que ha terminado. docker compose logs clickhouse muestra cuál de las dos situaciones ocurre y docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled informa true cuando el kernel lo termina por falta de memoria. Esto indica que el servidor es demasiado pequeño, no que la configuración sea incorrecta.

Después, la migración y las aplicaciones:

pnpm --filter @superlog/db db:migrate
pnpm dev

Preste atención al puerto: 5434, no 5432. El archivo compose publica Postgres en 5434 para no entrar en conflicto con una instancia de Postgres ya instalada en el host. Los archivos de la aplicación .env.example coinciden y usan DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Si apunta la migración a 5432 en un servidor que ya ejecuta Postgres, puede obtener una conexión rechazada o, peor aún, aplicar la migración a la base de datos equivocada.

pnpm dev inicia los cuatro procesos indicados en Procfile del repositorio: api, web, worker y proxy. Cada proceso envía una copia de su salida a tmp/logs/, por lo que tail -f tmp/logs/proxy.log es el lugar donde debe supervisar la ingesta. El README configura la aplicación web en http://localhost:5173, la API en http://localhost:4100 y la entrada OTLP en http://localhost:4101.

Confirme qué proceso está escuchando realmente antes de dirigirle conexiones:

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

Esto será importante más adelante. El proxy lee su propio puerto de la variable de entorno PORT y usa 4000 cuando PORT no está definida. La pila de desarrollo la establece automáticamente. Una unidad de systemd que escriba usted no lo hace, por lo que un exporter dirigido a 4101 mientras el proxy escucha en 4000 falla con una conexión rechazada y no proporciona ninguna otra pista.

Enviar una traza, generar un error y ver un incidente

Cree un proyecto en la aplicación web y copie su clave de ingesta. El punto de ingesta autentica cada solicitud con esa clave, por lo que la telemetría enviada sin ella nunca llega a ClickHouse.

Apunte cualquier SDK de OpenTelemetry al punto de ingesta mediante 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'

El punto de ingesta lee la clave de la cabecera x-api-key y también acepta authorization: bearer YOUR_INGEST_KEY si el exportador se configura más fácilmente de esa forma. Sirve las tres rutas OTLP estándar, /v1/traces, /v1/logs y /v1/metrics, además de /health.

Conviene señalar un error frecuente. 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 usan exactamente como están escritas, sin añadir ninguna ruta. Si establece la variable específica de señal en http://127.0.0.1:4101, cada exportación se envía a /, que no es una ruta. Por tanto, no llega nada y el SDK registra un error de exportación mientras la aplicación parece funcionar correctamente.

En un servicio de Node, la ruta sin código adicional basta para comprobar la canalización:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

Ahora provoque un fallo de forma intencionada. Cualquier ruta que genere una excepción sirve:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

Compruebe los saltos en orden. El primer punto sin actividad indica 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 contador creciente en otel_traces con la aplicación web vacía indica una discrepancia de proyecto. Compruebe a qué proyecto pertenece la clave de ingesta. Un contador sin cambios con actividad en el registro del proxy apunta al collector o a la escritura en ClickHouse. En ese caso, lea docker compose logs collector. Si no hay ninguna actividad en el registro del proxy, el exportador nunca llegó al punto de ingesta: el puerto o la ruta son incorrectos, o la clave fue rechazada.

En la aplicación web, esos fallos repetidos llegan como un solo incidente, no como una fila por solicitud. Superlog calcula la huella de las señales entrantes y agrupa las que coinciden. Esto evita tener una bandeja de entrada con 4,000 errores idénticos y muestra una sola incidencia. Después, el agente escribe su investigación sobre ese grupo.

El paso de investigación llama a un modelo, por lo que el worker necesita un proveedor de modelos configurado. Obtenga esos nombres de variables del archivo .env.example dentro del directorio de cada aplicación del commit que fijó, no de una documentación externa, porque cambian junto con main. Lo mismo se aplica a las integraciones de GitHub y Sentry. Cada una tiene sus propios documentos de configuración en docs/github-app-setup.md y docs/sentry-app-setup.md, y los payloads de webhook están documentados en docs/webhooks.md.

Mantenga la entrada privada y el agente en modo de solo lectura

Docker publica los puertos de los contenedores en 0.0.0.0 de forma predeterminada. Esos puertos publicados omiten ufw porque Docker escribe sus propias reglas en la cadena DOCKER-USER, que se evalúan antes de que ufw vea el paquete. En un VPS con una IP pública, el archivo compose distribuido expone ClickHouse HTTP en 8123 y Postgres en 5434, de modo que Internet puede acceder a ellos. Las credenciales de ese archivo son valores predeterminados de desarrollo: el usuario de ClickHouse es default y tiene una contraseña vacía; en Postgres, postgres se usa como usuario y como contraseña.

Enlácelos a la interfaz de loopback. Cada puerto publicado en el archivo compose obtiene su lado del host de una variable de entorno, por lo que basta con crear un archivo .env en la raíz del repositorio:

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:4318

Verifique el resultado antes de confiar en él y, después, vuelva a crear los contenedores:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config muestra el archivo resuelto, de modo que puede leer 127.0.0.1:5434:5432 en lugar de hacer suposiciones. Después, ss debería mostrar 127.0.0.1:5434 y nunca 0.0.0.0:5434. No intente corregirlo con un archivo de sustitución de compose que vuelva a declarar ports, porque Compose concatena las listas de puertos entre archivos en lugar de reemplazarlas. Como resultado, terminaría con ambos enlaces y el puerto público seguiría abierto.

La entrada requiere el mismo cuidado. La clave de ingesta viaja en una cabecera, por lo que necesita TLS (seguridad de la capa de transporte) delante: termine TLS en nginx o Caddy antes del proxy, o mantenga la ingesta dentro de una red privada o un túnel de WireGuard. La aplicación web en 5173 es un servidor de desarrollo de Vite y no debe estar expuesta a Internet.

Después está el propio agente. La propuesta de Superlog es que el agente investigue y proponga una corrección. La palabra importante es «proponga». Manténgalo en modo de solo lectura frente a producción hasta haber observado su funcionamiento en varios incidentes reales. Asigne a la GitHub App permisos de lectura y permita que abra pull requests que usted pueda revisar. Un agente que lee la telemetría y escribe un parche resulta útil. Un agente que puede reiniciar sus servicios implica otro nivel de riesgo. Esa debe ser una decisión tomada de forma deliberada, no un valor predeterminado que se adopta sin más. El coste requiere la misma atención, porque cada investigación es una llamada a un modelo: consulte el 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 hizo realmente el agente para que cualquier pull request inesperada tenga un rastro de auditoría.

Fallos habituales y las cadenas que los identifican

• ERR_PNPM_UNSUPPORTED_ENGINE durante pnpm install significa que Node es anterior a 20. node -v lo confirma en una línea.
• ECONNREFUSED 127.0.0.1:5434 durante la migración significa que la pila de compose no está activa o que DATABASE_URL indica el puerto incorrecto.
• Que ClickHouse se reinicie en bucle suele deberse a la memoria. Lea docker compose logs clickhouse y compruebe después si el contenedor tiene OOMKilled establecido en true.
• Si un exporter informa de que todo funciona, pero la aplicación web sigue vacía, normalmente significa que los datos fueron directamente al collector en 4318. Así se omite la asignación del proyecto que realiza el proxy.
• Un error de conexión rechazada en 4101 en una instalación de producción significa que el proxy recurrió a PORT=4000. Establezca PORT explícitamente en el archivo de unidad.
• Si docker compose ps muestra 0.0.0.0:8123, los enlaces de loopback no están activos. Ejecute docker compose config y revise los puertos resueltos.

Flawless, HyperProbe y la posición de Superlog

Esta categoría es reciente, y las herramientas se diferencian por el nivel de acceso que puede tener el agente. Flawless es una herramienta SRE (ingeniería de fiabilidad del sitio) de IA y código abierto orientada a Kubernetes. Lee datos de un stack existente de Prometheus, Loki y Grafana, en lugar de gestionar la canalización.

HyperProbe adopta el enfoque contrario. Es un producto alojado y, en agosto de 2026, su código fuente es cerrado. Coloca probes de sólo lectura dentro de un proceso en ejecución para capturar el estado de las variables y expone ese estado a un asistente mediante MCP (protocolo de contexto del modelo).

Superlog se sitúa entre ambos. Gestiona toda la canalización, desde la recepción de OTLP hasta el almacenamiento en ClickHouse. Además, coloca el agente en el paso de triaje, no en el de corrección. Por eso alojar Superlog por cuenta propia es una decisión de infraestructura, no un contenedor que se instala y se olvida. Cuando ejecuta Superlog, también ejecuta un almacén de columnas. Necesita el mismo mantenimiento que cualquier otra base de datos bajo su control.

FAQ

¿Cuánta RAM necesita un Superlog autohospedado?

Reserve 8 GB de RAM, 4 vCPU y 40 GB de disco para un solo nodo con un volumen de ingesta bajo. La pila incluye Postgres, ClickHouse, un collector de OpenTelemetry y cuatro procesos de Node; además, ClickHouse necesita margen de recursos. Una VPS de 1 GB o 2 GB no es suficiente: pnpm install por sí solo consume muchos recursos y, bajo carga, el kernel finaliza ClickHouse mediante el asesino de procesos por falta de memoria. Mida sus propios valores con docker stats --no-stream y free -m en lugar de confiar en una cifra publicada, incluida esta.

¿A qué puerto debo apuntar mi exportador OTLP?

Al proxy de ingesta de Superlog, que el README configura en http://localhost:4101. Sirve /v1/traces, /v1/logs y /v1/metrics, y se autentica con la clave de ingesta del proyecto, tomada del encabezado x-api-key o de un encabezado authorization: bearer. El puerto 4318 pertenece al collector de OpenTelemetry subyacente. Exportar directamente a ese puerto omite el proxy, que es el componente que añade el identificador del proyecto a los datos. El proxy usa el puerto 4000 si PORT no está definido. Ejecute ss -lntp y confirme en qué puerto está escuchando antes de asumir que es 4101.

¿Superlog sustituye a Uptime Kuma o Zabbix?

No. Uptime Kuma comprueba desde fuera de la red si un endpoint responde, y Zabbix supervisa las métricas del host y de los servicios según los umbrales que configure. Superlog consume las trazas, los registros y las métricas que generan sus aplicaciones, y agrupa los fallos repetidos en incidentes. Mantenga además una comprobación externa de disponibilidad, porque una comprobación ejecutada en otro lugar seguirá informando cuando el equipo que aloja la canalización de telemetría sea precisamente el que haya fallado.

¿Puede el agente de Superlog cambiar mis sistemas de producción?

Sólo mediante los permisos que le conceda. Su salida es una investigación y una propuesta de cambio que revisa una persona. Al principio, mantenga la GitHub App con permisos de lectura y solicitudes de incorporación de cambios, y limite a la lectura las credenciales que tenga el worker. Considere el acceso de escritura a producción como una decisión independiente y deliberada, porque un agente que puede reiniciar servicios implica un compromiso mucho mayor que uno que lee la telemetría y escribe un parche para revisión.

¿Debo fijar un commit o seguir main?

Fije un commit. En agosto de 2026 no hay etiquetas de versión en el repositorio, por lo que main es el único objetivo móvil disponible y recibe varios commits por semana. Registre el SHA que probó, implemente ese commit y revise el diff antes de actualizarlo. git log --oneline <old-sha>..main contiene la revisión, y los archivos .env.example de cada aplicación son el primer lugar que debe consultar para encontrar variables nuevas que sean necesarias después de cualquier actualización.