Como hospedar o Superlog para triagem de logs com IA

O que a instalação self-hosted do Superlog instala

Para alojar o Superlog por conta própria, clone o repositório, inicie o Postgres, o ClickHouse e um coletor OpenTelemetry com Docker Compose, execute uma migração da base de dados e depois inicie quatro serviços Node a partir do código-fonte. As suas aplicações enviam traces, logs e métricas através de OTLP (protocolo OpenTelemetry) para uma porta de ingestão. O Superlog calcula uma impressão digital desses dados, agrupa os eventos repetidos num único incidente e um agente escreve a primeira versão da triagem. A instalação ocupa uma tarde. A dimensão da instalação e as suas limitações reais são os pontos que vale a pena ler antes de começar.

O Superlog é distribuído sob a licença Apache 2.0 e está disponível em github.com/superloglabs/superlog. Em agosto de 2026, tem cerca de 1.2k estrelas, aproximadamente 460 commits em main e não tem quaisquer tags de versão. Este último ponto condiciona a instalação: git checkout v1.0.0 não tem nada para obter, por isso fixa um commit por sua conta ou executa a versão de main que estava disponível na manhã em que fez o clone.

O que o Superlog responde e o Uptime Kuma e o Langfuse não

As ferramentas de monitorização self-hosted parecem equivalentes à primeira vista. Não são, e executar a ferramenta errada consome recursos do servidor sem benefício.

• O Uptime Kuma testa os seus endpoints a partir do exterior e responde a uma pergunta: está disponível.
• O Zabbix monitoriza hosts e serviços no Ubuntu 24.04, comparando CPU, memória, disco e estado dos serviços com os limites que definiu.
• O Langfuse rastreia chamadas a LLM, registando o prompt, o modelo, os tokens, a latência e o custo de cada chamada.
• O Superlog recolhe a telemetria que os seus serviços comuns já emitem e transforma falhas repetidas em incidentes.

O Superlog responde a uma pergunta diferente: algo falhou, o que falhou e porquê. Não foi concebido para chamadas a LLM e não faz testes externos ao seu serviço. Recebe dados OTLP do código normal da aplicação e coloca um agente na etapa de triagem, que corresponde à primeira análise que uma pessoa de plantão faria de qualquer forma.

A diferença relevante para o orçamento de um VPS está no armazenamento. O Uptime Kuma funciona sem problemas com 1 GB de RAM porque armazena alguns milhares de resultados de verificações. O Superlog usa um armazenamento colunar, porque a telemetria é gravada uma vez e depois consultada por intervalo de tempo em milhões de linhas. É para isso que serve o ClickHouse e é por isso que o Postgres não serve. O Postgres continua na stack e armazena os poucos dados relacionais: projetos, utilizadores, incidentes e chaves de ingestão.

O que o comando docker compose up -d inicia de facto?

Três contentores, e nenhum deles é o Superlog. Isto surpreende quem espera uma instalação com um único comando.

• postgres:16, publicado na porta 5434 do host
• clickhouse/clickhouse-server:26.1, na porta 8123 para HTTP e na porta 9000 para o protocolo nativo
• otel/opentelemetry-collector-contrib:0.150.1, na porta 4317 para gRPC e na porta 4318 para OTLP sobre HTTP

As aplicações Superlog são executadas no host a partir do código-fonte e iniciadas por pnpm dev. Em agosto de 2026, não existe um ficheiro compose para produção no repositório. Por isso, uma instalação de longa duração exige as suas próprias unidades systemd para cada script start das aplicações ou os Dockerfiles de cada aplicação incluídos na árvore.

Tenha presente o caminho percorrido por um span, porque cada falha abaixo corresponde a uma interrupção num dos seus saltos. A aplicação envia OTLP para o proxy de ingestão do Superlog. O proxy autentica o pedido com a sua chave de ingestão, atribui-lhe o id do projeto e encaminha-o para o collector. O collector remove quaisquer atributos superlog.* que o cliente tenha tentado definir, adiciona superlog.project_id a partir do cabeçalho fornecido pelo proxy, agrupa os dados e grava-os no ClickHouse. A aplicação web e a API leem a telemetria do ClickHouse e obtêm todos os outros dados do Postgres.

A remoção desses atributos é um controlo real de multi-tenancy, não um elemento meramente decorativo. Sem ela, qualquer pessoa com uma chave de ingestão válida poderia definir superlog.project_id por sua conta e gravar dados no projeto de outra pessoa.

Qual deve ser o tamanho do VPS?

Planeie 4 vCPU, 8 GB de RAM e 40 GB de SSD para uma instalação de nó único com baixo volume de ingestão. Esse valor é um limite de planeamento, não uma medição. Use-o como tamanho inicial e valide-o com base no seu próprio tráfego.

A memória é distribuída por quatro componentes. O ClickHouse foi concebido para máquinas com muita RAM e as predefinições partem desse princípio. O Postgres 16 é moderado neste cenário, porque armazena metadados e não telemetria. O collector também consome pouco. Os quatro processos Node não são moderados: um servidor de desenvolvimento Vite e três processos tsx watch mantêm centenas de megabytes cada um, por isso pnpm dev num servidor com 2 GB torna-se problemático.

O disco é o problema menos evidente. pnpm install neste monorepo instala o AWS SDK, um cliente ClickHouse, o OpenTelemetry SDK e uma toolchain React antes de ingerir um único span. Depois, o ClickHouse cresce com o tráfego. Meça 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"

Com baixo volume, alguns serviços a enviar algumas centenas de spans por minuto, o servidor mantém-se inativo e o ClickHouse passa a maior parte do tempo sem carga. O que causa problemas são os picos: uma implementação com falhas pode produzir milhares de erros idênticos por minuto. A identificação por fingerprinting agrupa esses erros num único incidente para o leitor, mas o ClickHouse continua a gravar cada linha subjacente.

A retenção é definida por si. O exporter ClickHouse do collector cria as tabelas, otel_traces, otel_logs e uma tabela por tipo de métrica. Só aplica um time to live se a configuração em infra/collector/config.yaml definir um. Nada expira automaticamente. Por isso, um mês com muito tráfego pode encher o disco se não planear esse limite.

Instale a partir de um commit fixado

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l não imprimir nada é o resultado esperado em agosto de 2026. Escolha o commit que testou e mantenha-se nele:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Em seguida, a cadeia de ferramentas:

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

package.json declara engines.node como >=20.0.0 e packageManager como pnpm@9.12.0. Se executar a instalação com uma versão mais antiga do Node, o pnpm termina com ERR_PNPM_UNSUPPORTED_ENGINE e indica a versão necessária. O pacote nodejs no arquivo do Ubuntu 24.04 é anterior à versão 20, portanto instale o Node 20 ou posterior a partir do NodeSource ou do nvm. O repositório inclui um .nvmrc, portanto nvm use seleciona a versão pretendida se tiver o nvm.

pnpm install
docker compose up -d
docker compose ps

Aguarde as verificações de integridade em vez de interpretar up -d como indicação de que o serviço está pronto. O Postgres e o ClickHouse declaram uma verificação no ficheiro compose:

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

O ClickHouse responde Ok. e pg_isready responde accepting connections. Uma recusa de ligação na porta 8123 significa que o contentor ainda está a iniciar ou terminou. docker compose logs clickhouse mostra qual das situações ocorreu, e docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled indica true quando o kernel o termina por falta de memória. Isso indica que o servidor é demasiado pequeno, e não que a configuração esteja errada.

Depois, execute a migração e inicie as aplicações:

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

Tenha atenção à porta: 5434, não 5432. O ficheiro compose publica o Postgres na porta 5434 para evitar conflitos com um Postgres já instalado no host, e os ficheiros .env.example da aplicação correspondem a essa configuração, com DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Se apontar a migração para a porta 5432 num servidor que já executa o Postgres, pode obter uma ligação recusada ou, pior, aplicar a migração à base de dados errada.

pnpm dev inicia os quatro processos listados no Procfile do repositório: api, web, worker e proxy. Cada processo encaminha a sua saída para tmp/logs/, portanto tail -f tmp/logs/proxy.log é o local onde deve monitorizar a ingestão. O README define a aplicação web em http://localhost:5173, a API em http://localhost:4100 e a receção OTLP em http://localhost:4101.

Confirme o que efetivamente ficou associado a uma porta antes de apontar qualquer componente para esse serviço:

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

Isto será importante mais tarde. O proxy lê a própria porta da variável de ambiente PORT e utiliza a porta 4000 quando PORT não está definida. A stack de desenvolvimento configura-a automaticamente. Uma unidade systemd que criar manualmente não o faz. Por isso, um exporter direcionado para a porta 4101, quando o proxy está a escutar na porta 4000, falha com uma ligação recusada e não fornece outra indicação.

Envie um trace, produza um erro, veja um incidente

Crie um projeto na aplicação web e copie a respetiva ingest key. O intake autentica cada pedido com essa chave. Por isso, a telemetria enviada sem ela nunca chega ao ClickHouse.

Aponte qualquer SDK OpenTelemetry para o intake usando as variáveis de ambiente padrão:

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'

O intake lê a chave do cabeçalho x-api-key e também aceita authorization: bearer YOUR_INGEST_KEY se o seu exporter for mais fácil de configurar dessa forma. Serve os três caminhos OTLP padrão, /v1/traces, /v1/logs e /v1/metrics, além de /health.

É importante identificar uma armadilha. OTEL_EXPORTER_OTLP_ENDPOINT é um URL base, e o SDK acrescenta-lhe o caminho do signal. As variáveis específicas do signal, como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, são usadas exatamente como estão, sem acrescentar qualquer caminho. Defina a variável específica do signal como http://127.0.0.1:4101 e cada export será enviado para /, que não é uma rota. Nada chega ao destino e o SDK regista uma falha de export, enquanto a aplicação parece saudável.

Num serviço Node, o caminho sem código adicional é suficiente para provar o pipeline:

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

Agora provoque uma falha de propósito. Qualquer rota que lance uma exceção serve:

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

Verifique os saltos pela ordem indicada. A primeira lacuna mostra qual falhou:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

Um contador crescente em otel_traces com a aplicação web vazia indica uma incompatibilidade de projeto. Verifique a que projeto pertence a ingest key. Um contador sem alterações, com atividade no log do proxy, aponta para o collector ou para a escrita no ClickHouse. Leia docker compose logs collector. A ausência total de atividade no log do proxy significa que o exporter nunca chegou ao intake: porta errada, caminho errado ou chave rejeitada.

Na aplicação web, essas falhas repetidas aparecem como um único incidente, e não como uma linha por pedido. O Superlog cria fingerprints dos sinais recebidos e agrupa os sinais correspondentes. Essa é a diferença entre uma caixa de entrada com 4,000 erros idênticos e uma página com um só erro. O agente escreve a investigação sobre esse grupo.

A etapa de investigação chama um modelo. Por isso, o worker precisa de um model provider configurado. Obtenha os nomes dessas variáveis no ficheiro .env.example dentro do diretório de cada aplicação do commit que fixou, e não em documentação externa, porque esses nomes acompanham main. O mesmo se aplica às integrações GitHub e Sentry. Cada uma tem a sua própria documentação de configuração em docs/github-app-setup.md e docs/sentry-app-setup.md, com os payloads dos webhooks documentados em docs/webhooks.md.

Mantenha a ingestão privada e o agente apenas com acesso de leitura

Por padrão, o Docker publica as portas dos contentores em 0.0.0.0. Essas portas publicadas contornam o ufw, porque o Docker escreve as suas próprias regras na cadeia DOCKER-USER, que são avaliadas antes de o ufw receber o pacote. Num VPS com um IP público, o ficheiro compose, tal como é fornecido, expõe o ClickHouse HTTP na porta 8123 e o Postgres na porta 5434, permitindo que a Internet lhes aceda. As credenciais desse ficheiro são valores predefinidos de desenvolvimento: o utilizador do ClickHouse é default com uma palavra-passe vazia, e o Postgres usa postgres como utilizador e palavra-passe.

Associe essas portas ao loopback. Todas as portas publicadas no ficheiro compose obtêm o lado do host a partir de uma variável de ambiente. Por isso, basta um ficheiro .env na raiz do repositório:

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 o resultado antes de confiar nele e recrie os contentores:

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

docker compose config mostra o ficheiro depois da resolução, para que possa ler 127.0.0.1:5434:5432 em vez de adivinhar. Em seguida, ss deve mostrar 127.0.0.1:5434 e nunca 0.0.0.0:5434. Não tente corrigir isto com um ficheiro de substituição do compose que volte a declarar ports, porque o Compose concatena as listas de portas entre ficheiros em vez de as substituir. O resultado teria ambas as associações, mantendo a porta pública aberta.

A ingestão exige o mesmo cuidado. A sua chave de ingestão é enviada num cabeçalho, por isso precisa de TLS (segurança da camada de transporte) à sua frente. Termine o TLS no nginx ou no Caddy antes do proxy, ou mantenha a ingestão numa rede privada ou num túnel WireGuard. A aplicação web na porta 5173 é um servidor de desenvolvimento Vite e não deve ficar exposta à Internet.

Agora, o próprio agente. A proposta do Superlog é que o agente investigue e proponha uma correção. A palavra importante é proponha. Mantenha-o apenas com acesso de leitura na produção até observar o seu funcionamento em alguns incidentes reais. Atribua à GitHub App permissões de leitura e permita que abra pull requests para sua revisão. Um agente que lê telemetria e escreve um patch é útil. Um agente que pode reiniciar os seus serviços representa um nível de risco diferente. Essa deve ser uma decisão tomada intencionalmente, e não uma predefinição herdada. Os custos exigem a mesma atenção, porque cada investigação é uma chamada ao modelo: defina um orçamento para os custos do agente num VPS antes de o direcionar para um sistema de produção com muito ruído e mantenha um registo do que o agente fez realmente para que uma pull request inesperada tenha um registo de auditoria associado.

Falhas que você encontrará e as mensagens que as identificam

• ERR_PNPM_UNSUPPORTED_ENGINE durante pnpm install significa que o Node é anterior à versão 20. node -v confirma isso numa linha.
• ECONNREFUSED 127.0.0.1:5434 durante a migração significa que a stack do compose não está em execução ou que DATABASE_URL indica a porta errada.
• O reinício contínuo do ClickHouse geralmente está relacionado com memória. Leia docker compose logs clickhouse e verifique se OOMKilled está definido como true no contentor.
• Um exporter que comunica sucesso enquanto a aplicação Web continua vazia geralmente indica que os dados foram diretamente para o collector na porta 4318. Isto ignora a atribuição do projeto feita pelo proxy.
• Um erro de ligação recusada na porta 4101 numa instalação de produção significa que o proxy recorreu a PORT=4000. Defina PORT explicitamente no ficheiro da unidade.
• docker compose ps a mostrar 0.0.0.0:8123 significa que as ligações em loopback não estão a ser aplicadas. Execute docker compose config e leia as portas resolvidas.

Flawless, HyperProbe e onde o Superlog se enquadra

Esta categoria ainda é recente, e as ferramentas diferem quanto ao que o agente pode tocar. O Flawless é uma ferramenta SRE (engenharia de fiabilidade de sites) de IA e código aberto, orientada para Kubernetes. Lê dados de uma stack Prometheus, Loki e Grafana existente, em vez de gerir o pipeline. O HyperProbe segue a abordagem oposta: é um produto alojado, de código fechado em agosto de 2026, que coloca probes apenas de leitura dentro de um processo em execução para capturar o estado das variáveis. Depois, expõe esse estado a um assistente através de MCP (protocolo de contexto do modelo).

O Superlog fica entre os dois. Gere o pipeline de ponta a ponta, desde a ingestão de OTLP até ao armazenamento no ClickHouse. Também coloca o agente na etapa de triagem, e não na etapa de correção. É precisamente por isso que alojá-lo internamente é uma decisão de infraestrutura, e não simplesmente um contentor que pode ser esquecido. Quando executa o Superlog, também executa um column store. Este requer os mesmos cuidados que qualquer outra base de dados sob a sua gestão.

FAQ

Quanta RAM é necessária para um Superlog auto-hospedado?

Planeie 8 GB de RAM, 4 vCPU e 40 GB de disco para um único nó com baixo volume de ingestão. A stack inclui Postgres, ClickHouse, um coletor OpenTelemetry e quatro processos Node, e o ClickHouse precisa de margem de recursos. Um VPS com 1 GB ou 2 GB não é suficiente: só o pnpm install é pesado, e o ClickHouse é terminado pelo OOM killer do kernel sob carga. Meça os seus próprios valores com docker stats --no-stream e free -m em vez de confiar em qualquer valor publicado, incluindo este.

Para que porta devo apontar o meu exportador OTLP?

Para o proxy de ingestão do Superlog, que o README indica em http://localhost:4101. Ele disponibiliza /v1/traces, /v1/logs e /v1/metrics e autentica com a chave de ingestão do seu projeto, obtida do cabeçalho x-api-key ou de um cabeçalho authorization: bearer. A porta 4318 pertence ao coletor OpenTelemetry subjacente. Exportar diretamente para essa porta ignora o proxy, que é o componente que adiciona o ID do projeto aos dados. O proxy usa a porta 4000 quando PORT não está definida. Execute ss -lntp e confirme a porta à qual ele ficou associado antes de assumir que é 4101.

O Superlog substitui o Uptime Kuma ou o Zabbix?

Não. O Uptime Kuma indica se um endpoint responde a partir do exterior da sua rede, e o Zabbix monitoriza métricas do host e dos serviços com base nos limites que definir. O Superlog consome os traces, logs e métricas emitidos pelas suas aplicações e agrupa falhas repetidas em incidentes. Mantenha uma verificação externa de disponibilidade em paralelo, porque uma verificação executada noutro local continua a indicar quando o servidor que aloja o seu pipeline de telemetria é o componente que falhou.

O agente do Superlog pode alterar os meus sistemas de produção?

Apenas através das permissões que lhe conceder. O resultado é uma investigação e uma alteração proposta que um humano revê. Inicialmente, mantenha a GitHub App apenas com permissões de leitura e pull requests, e mantenha limitadas à leitura quaisquer credenciais detidas pelo worker. Trate o acesso de escrita à produção como uma decisão separada e deliberada, porque um agente que pode reiniciar serviços representa um compromisso muito maior do que um agente que lê telemetria e escreve um patch para revisão.

Devo fixar um commit ou acompanhar a main?

Fixe um commit. Em agosto de 2026, o repositório não tem tags de release, por isso main é o único alvo móvel disponível e recebe vários commits por semana. Registe o SHA que testou, faça o deploy dessa versão e leia o diff antes de avançar. git log --oneline <old-sha>..main é a revisão, e os ficheiros .env.example específicos de cada aplicação são o primeiro local a consultar para encontrar variáveis novas obrigatórias depois de qualquer atualização.