SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-11-06

Como hospedar o Superlog para triagem de logs por IA

Veja o que o Superlog instala: Postgres, ClickHouse, OpenTelemetry e quatro serviços Node, além do limite real de recursos no seu próprio VPS.

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

Para alojar o Superlog no seu próprio ambiente, 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, em seguida, inicie quatro serviços Node a partir do código-fonte. As suas aplicações enviam traces, logs e métricas OTLP (protocolo OpenTelemetry) para uma porta de ingestão. O Superlog calcula uma impressão digital para cada evento, agrupa os eventos repetidos num único incidente e o executor de agentes comunitário predefinido regista um resumo local do incidente. A instalação demora uma tarde. A dimensão da implementação e as limitações reais são os aspetos que vale a pena ler antes de começar.

O Superlog é licenciado ao abrigo da Apache 2.0 e está disponível em github.com/superloglabs/superlog. Em 13 October 2026, tem cerca de 1.5k stars, aproximadamente 490 commits em main e não tem quaisquer tags de release. Fixe você mesmo um commit, em vez de executar o estado em que main se encontrava na manhã em que o clonou.

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

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

O Superlog responde a uma pergunta diferente: algo falhou, o que falhou e porquê. Não gere chamadas LLM e não testa o seu sistema a partir do exterior. Recebe dados OTLP do código normal da sua 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 distinção importante para o orçamento de um VPS é o armazenamento. O Superlog inclui um column store, porque a telemetria é escrita uma vez e depois consultada por intervalo de tempo em milhões de linhas. É para isso que serve o ClickHouse, e não o Postgres. O Postgres continua na stack e armazena os pequenos dados relacionais: projetos, utilizadores, incidentes e chaves de ingestão.

O que é iniciado exatamente por docker compose up -d?

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 anfitrião
  • clickhouse/clickhouse-server:26.1, na porta 8123 para HTTP e 9000 para o protocolo nativo
  • otel/opentelemetry-collector-contrib:0.150.1, na porta 4317 para gRPC e 4318 para OTLP sobre HTTP

As aplicações do Superlog são executadas no anfitrião, a partir do código-fonte, e iniciadas por pnpm dev. Em 13 October 2026, não existe um ficheiro compose de produção no repositório. Por isso, uma instalação de longa duração requer as suas próprias unidades systemd ou os Dockerfiles de cada aplicação fornecidos na árvore de código. As aplicações api, worker e proxy têm cada uma um script start que pode ser encapsulado numa unidade. A aplicação web não tem nenhum: é uma aplicação Vite. Por isso, compile-a com o seu script build e sirva o resultado como ficheiros estáticos através do nginx ou do Caddy, ou execute o seu script preview, que corresponde a vite preview.

Mantenha na memória o percurso que um intervalo percorre, porque cada falha abaixo corresponde a uma interrupção num dos seus saltos. A sua aplicação envia OTLP para o proxy de ingestão do Superlog. O proxy autentica o pedido com a sua chave de ingestão, adiciona-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 no ClickHouse e obtêm todos os restantes dados no Postgres.

A remoção desses atributos é um controlo real de multilocação, não um elemento decorativo. Sem ela, qualquer pessoa que possua uma chave de ingestão válida poderia definir superlog.project_id e gravar dados no projeto de outra pessoa.

Qual é o tamanho necessário para o 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 é um limite mínimo de planeamento, não uma medição. Use-o como ponto de partida e compare-o com o seu próprio tráfego.

A memória é usada por quatro componentes. O ClickHouse foi concebido para máquinas com muita RAM, e os valores predefinidos partem desse pressuposto. O Postgres 16 tem um consumo moderado neste caso, porque armazena metadados, não telemetria. O coletor também tem um consumo moderado. Os quatro processos Node incluem um servidor de desenvolvimento Vite e três processos tsx watch. Meça o consumo de memória no seu próprio servidor.

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 seu 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"

A carga problemática ocorre durante os picos: uma implementação com problemas pode produzir milhares de erros idênticos por minuto. A identificação por fingerprint agrupa esses erros num único incidente para o leitor, mas o ClickHouse continua a gravar todas as linhas.

A retenção é definida por si. O exportador ClickHouse do coletor cria as tabelas, otel_traces, otel_logs e uma tabela para cada tipo de métrica. Ele 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 tráfego elevado pode encher o disco se não houver planeamento.

Instalar 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 exibir nada é o resultado esperado em 13 de outubro de 2026. Escolha o commit que testou e mantenha-se nele:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Agora, 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. Uma versão incompatível do Node não interrompe automaticamente a instalação: a imposição da versão do engine depende da configuração, e o pnpm 9.12.0 tem um caminho de aviso quando engineStrict está desativado. O pacote nodejs no arquivo do Ubuntu 24.04 é anterior à versão 20. Portanto, instale o Node 20 ou mais recente 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 considerar up -d como indicação de que o serviço está pronto. Postgres e ClickHouse declaram uma verificação no arquivo compose:

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

O ClickHouse responde em Ok. e pg_isready responde em accepting connections. Uma conexão recusada na porta 8123 significa que o container ainda está a iniciar ou terminou. docker compose logs clickhouse mostra qual dos casos ocorreu, e docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled informa true quando o kernel o encerra por falta de memória. Isso indica que a máquina é pequena demais, e não que a configuração está incorreta.

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

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

Observe a porta: 5434, não 5432. O arquivo compose publica o Postgres na porta 5434 para não colidir com um Postgres já instalado no host. Os arquivos da aplicação .env.example correspondem a essa configuração, com DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Se apontar a migração para a porta 5432 numa máquina que já executa o Postgres, terá uma conexão recusada ou, pior, aplicará a migração no banco de dados errado.

pnpm dev executa turbo run dev, que inicia o script dev de cada aplicação por meio do Turborepo, incluindo api, web, worker e proxy, com a saída misturada num único terminal. O Procfile do repositório lista os mesmos quatro processos e envia a saída de cada um para tmp/logs/. Inicie-o com um executor de Procfile, como overmind ou foreman, em vez de pnpm dev, se quiser que tail -f tmp/logs/proxy.log seja o local onde monitoriza o ingest. O README define a aplicação web em http://localhost:5173, a API em http://localhost:4100 e a receção de OTLP em http://localhost:4101.

Confirme o que realmente ficou associado a uma porta antes de o utilizar:

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

Isto será importante mais adiante. O proxy lê a sua própria porta da variável de ambiente PORT e usa 4000 quando PORT não está definida. O apps/proxy/.env.example que carrega também define PORT=4000, embora o README liste a receção em 4101. Ambos os valores foram verificados em 13 de outubro de 2026. Use a porta mostrada por ss. Os exemplos abaixo usam 4101; substitua-a por 4000 se essa for a porta associada. Uma unidade systemd criada por si não define nada, a menos que inclua PORT nela. Portanto, um exporter direcionado para 4101 enquanto o proxy escuta em 4000 falha com uma conexão recusada e não fornece nenhuma 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 key, 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 key 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.

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

Para um serviço Node, o caminho sem alterações no código é suficiente para confirmar 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 por ordem, porque a primeira falha indica qual deles não funcionou:

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

Um valor crescente em otel_traces com a aplicação web vazia indica uma incompatibilidade de projeto. Verifique a que projeto pertence a ingest key. Um valor estável, 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 key rejeitada.

Na aplicação web, essas falhas repetidas chegam 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 apenas um. O agent runner comunitário predefinido regista então um resumo de incidente local para esse grupo.

Uma investigação baseada num modelo precisa de um model provider e de um agent runner compatível configurados; o runner comunitário predefinido regista um resumo local. Obtenha esses nomes de variáveis no ficheiro .env.example dentro do diretório de cada aplicação do commit que fixou, e não num guia externo, porque eles mudam com main. O mesmo se aplica às integrações do GitHub e do Sentry, que têm os seus próprios documentos de configuração em docs/github-app-setup.md e docs/sentry-app-setup.md, com os payloads de webhook documentados em docs/webhooks.md.

Mantenha a entrada privada e o agente somente com acesso de leitura

O Docker publica as portas dos contentores em 0.0.0.0 por predefinição, e essas portas publicadas ignoram o ufw. O Docker encaminha o tráfego dos contentores na tabela nat, portanto um pacote destinado a uma porta publicada é desviado antes de chegar às cadeias INPUT e OUTPUT, onde ficam as regras do ufw. O ufw nunca consegue avaliá-lo. Num VPS com um IP público, o ficheiro compose, tal como é fornecido, expõe o HTTP do ClickHouse na porta 8123 e o Postgres na porta 5434 à Internet. As credenciais desse ficheiro são predefinições de desenvolvimento: o utilizador default do ClickHouse com uma palavra-passe vazia, e o Postgres com 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, portanto 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

Confirme 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 apresenta o ficheiro resolvido, para que possa ler 127.0.0.1:5434:5432 em vez de tentar adivinhar. Em seguida, ss deve apresentar 127.0.0.1:5434 e nunca 0.0.0.0:5434. Simplesmente declarar ports novamente num ficheiro de substituição do Compose mantém ambas as associações quando o IP do host é diferente; o Compose 2.24.4 e versões posteriores suportam ports: !override para substituir a lista.

A entrada requer o mesmo cuidado. A chave de ingestão é enviada num cabeçalho, portanto 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 estar exposta à Internet.

Depois, o próprio agente. A proposta do Superlog é que o agente investigue e proponha uma correção, e a palavra importante é proponha. Mantenha-o com acesso somente de leitura na produção até observar o seu funcionamento em alguns incidentes reais. Uma GitHub App somente de leitura não pode enviar um branch de correção nem abrir pull requests: o guia de configuração exige permissões de escrita para Contents e Pull requests nesse fluxo, além de permissão de escrita para Issues para publicar comentários. 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, e essa deve ser uma decisão tomada de forma consciente, não uma predefinição herdada. Os custos merecem a mesma atenção ao configurar um executor baseado num modelo: defina um orçamento para os gastos 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 realmente fez para que um pull request inesperado tenha um registo de auditoria associado.

Falhas que vai encontrar e as mensagens que as identificam

  • ERR_PNPM_UNSUPPORTED_ENGINE durante pnpm install significa que um requisito do motor é incompatível. O pnpm 9.12.0 verifica os requisitos do Node e do pnpm; leia as versões pretendida e atual no erro e, em seguida, consulte node -v e pnpm -v.
  • ECONNREFUSED 127.0.0.1:5434 durante a migração significa que a stack do compose não está ativa ou que DATABASE_URL define a porta errada.
  • Verifique os reinícios do ClickHouse com docker compose logs clickhouse e, em seguida, confirme no contentor se OOMKilled está true.
  • Um exporter que indica sucesso enquanto a aplicação Web continua vazia normalmente significa que os dados foram diretamente para o collector na porta 4318, ignorando a identificação do projeto que o proxy aplica.
  • Uma recusa de ligação na porta 4101 normalmente significa que o proxy está a escutar na porta 4000, que é a porta usada pelo código como fallback e definida por .env.example. Defina PORT explicitamente no ficheiro da unidade ou em .env da aplicação.
  • docker compose ps a mostrar 0.0.0.0:8123 significa que as associações de loopback não estão a ser aplicadas. Execute docker compose config e leia as portas resolvidas.

Falwless, HyperProbe e onde o Superlog se enquadra

Esta categoria é recente, e as ferramentas diferem quanto ao que o agente pode manipular. O repositório Flawless agora apresenta o CISRE, uma plataforma de AI SRE (engenharia de fiabilidade de sites) para Kubernetes e infraestrutura de cloud, sob a licença PolyForm Noncommercial. O HyperProbe coloca probes dentro de um processo em execução para capturar o estado das variáveis e disponibiliza esse estado a um assistente através de MCP (protocolo de contexto de modelo). Também documenta a implementação self-hosted com Docker Compose e uma chave de licença.

O Superlog fica entre as duas. Gere o pipeline de ponta a ponta, desde a receção de OTLP até ao armazenamento no ClickHouse, e coloca o agente na etapa de triagem, não na etapa de correção. Por isso, executar o Superlog como self-hosted é uma decisão de infraestrutura, não apenas um contentor que pode ser esquecido. Ao executar o Superlog, também executa um column store, que precisa dos mesmos cuidados que qualquer outra base de dados sob a sua administração.

FAQ

De quanta RAM precisa o Superlog autoalojado?

Reserve 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. 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 configura em http://localhost:4101. O proxy disponibiliza /v1/traces, /v1/logs e /v1/metrics e autentica-se 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 é usada pelo coletor OpenTelemetry subjacente. Exportar diretamente para essa porta ignora o proxy, que é o componente responsável por associar o ID do projeto aos dados. O proxy usa a porta 4000 quando PORT não está definida, e .env.example também define 4000. Por isso, execute ss -lntp e confirme em que porta o serviço ficou a escutar antes de assumir que é a 4101.

O Superlog substitui o Uptime Kuma ou o Zabbix?

Não. O Uptime Kuma verifica, a partir do exterior da sua rede, se um endpoint responde. O Zabbix monitoriza métricas de hosts e serviços em relação aos limites que definiu. 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 runner comunitário predefinido regista um resumo local do incidente. Outros ambientes de execução de investigação dependem do runner que configurar. Mantenha as credenciais de produção limitadas a operações de leitura. A abertura de pull requests exige permissões de escrita separadas no GitHub para branches e pull requests. Trate o acesso de escrita à produção como uma decisão independente e deliberada. 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 13 October 2026, o repositório não tinha tags de release. 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 de cada aplicação são o primeiro local a consultar para encontrar variáveis novas obrigatórias depois de qualquer atualização.

Este artigo foi útil?