SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor · Bijgewerkt 2026-11-06

Superlog self-hosten voor AI-getriageerde logs

Ontdek wat Superlog echt installeert: Postgres, ClickHouse, vier Node-services en een OpenTelemetry Collector, plus de beperkingen van de stack.

Wat self-hosting van Superlog daadwerkelijk installeert

Voor self-hosting van Superlog clonet u de repository, start u Postgres, ClickHouse en een OpenTelemetry Collector met Docker Compose, voert u één databasemigratie uit en start u vervolgens vier Node-services vanuit de broncode. Uw applicaties sturen OTLP-traces, logs en metrics naar een intakepoort. Superlog maakt hiervan fingerprints, groepeert terugkerende exemplaren in één incident en de standaard community-agentrunner legt een lokale incidentsamenvatting vast. De installatie neemt een middag in beslag. De benodigde resources en de reële beperkingen zijn de onderdelen die u moet lezen voordat u begint.

Superlog valt onder de Apache 2.0-licentie en staat op github.com/superloglabs/superlog. Op 13 oktober 2026 heeft het project ongeveer 1.5k sterren, circa 490 commits op main en helemaal geen releasetags. Pin daarom zelf een commit in plaats van zonder controle te gebruiken wat er op de ochtend waarop u de repository clonet toevallig op main stond.

Wat Superlog beantwoordt en Uptime Kuma en Langfuse niet

Zelfgehoste monitoringtools lijken van buitenaf uitwisselbaar. Dat zijn ze niet. De verkeerde keuze kost u een server zonder voordeel.

Superlog beantwoordt een andere vraag: er is iets defect, wat is defect en waarom. Het heeft geen mening over LLM-aanroepen en controleert uw omgeving niet van buitenaf. Het verwerkt OTLP uit uw normale applicatiecode en zet een agent in op de triagestap. Dat is de eerste controle die een dienstdoende beheerder anders ook zou uitvoeren.

Voor het budget van een VPS is de opslag het belangrijkste verschil. Superlog bevat een kolomopslag, omdat telemetrie één keer wordt geschreven en daarna op tijdsbereik over miljoenen rijen wordt opgevraagd. Daarvoor is ClickHouse bedoeld, en niet Postgres. Postgres blijft wel onderdeel van de stack en bevat de beperkte relationele gegevens: projecten, gebruikers, incidenten en ingest keys.

Wat start docker compose up -d precies op?

Drie containers, en geen daarvan is Superlog. Dit verrast mensen die een installatie met één commando verwachten.

  • postgres:16, gepubliceerd op hostpoort 5434
  • clickhouse/clickhouse-server:26.1, op 8123 voor HTTP en 9000 voor het native protocol
  • otel/opentelemetry-collector-contrib:0.150.1, op 4317 voor gRPC en 4318 voor OTLP over HTTP

De Superlog-applicaties draaien op de host, vanuit de broncode, gestart door pnpm dev. Er is op 13 oktober 2026 geen productie-compose-bestand in de repository aanwezig, dus een langdurige installatie betekent dat u uw eigen systemd-units moet gebruiken, of de per-app Dockerfiles die in de tree worden meegeleverd. De api-, worker- en proxy-apps hebben elk een start-script voor een unit om in te kapselen. De web-app heeft er geen: het is een Vite-app, dus u bouwt deze met het build-script en serveert de output als statische bestanden vanaf nginx of Caddy, of u voert het preview-script uit, wat vite preview is.

Houd het pad dat een span aflegt in gedachten, want elke fout hieronder is een onderbreking in een van de stappen. Uw app verstuurt OTLP naar de Superlog intake-proxy. De proxy authenticeert het verzoek met uw ingest-key, voorziet het van het project-id en stuurt het door naar de collector. De collector verwijdert alle superlog.*-attributen die de client probeerde in te stellen, voegt superlog.project_id toe vanuit de header die de proxy heeft verstrekt, groepeert de data en schrijft deze naar ClickHouse. De web-app en de API lezen vervolgens telemetrie terug uit ClickHouse en al het overige uit Postgres.

Dat strippen van attributen is een echte multi-tenancy-controle, geen versiering. Zonder dit zou iedereen met een geldige ingest-key zelf superlog.project_id kunnen instellen en data in het project van een ander kunnen schrijven.

Hoe groot moet de VPS zijn?

Plan voor 4 vCPU, 8 GB RAM en 40 GB SSD voor een installatie met één node en een lage ingestvolumebelasting. Dit is een minimale planningswaarde, geen meting. Gebruik deze omvang daarom als uitgangspunt en controleer die aan de hand van uw eigen verkeer.

Het geheugen wordt over vier onderdelen verdeeld. ClickHouse is ontworpen voor machines met veel RAM en de standaardinstellingen gaan daarvan uit. Postgres 16 gebruikt hier weinig geheugen, omdat het metadata en geen telemetrie opslaat. Ook de collector gebruikt weinig geheugen. De vier Node-processen omvatten een Vite-developmentserver en drie tsx watch-processen. Meet het geheugengebruik op uw eigen systeem.

Schijfruimte is het minder zichtbare probleem. pnpm install in deze monorepo haalt de AWS SDK, een ClickHouse-client, de OpenTelemetry SDK en een React-toolchain op voordat u één span hebt verwerkt. ClickHouse groeit daarna mee met uw verkeer. Meet beide:

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"

De belasting die problemen veroorzaakt, ontstaat tijdens pieken: één slechte deployment kan per minuut duizenden identieke fouten produceren. Fingerprinting voegt deze voor de lezer samen tot één incident, maar ClickHouse schrijft onderliggend nog steeds elke rij.

U bepaalt zelf de bewaartermijn. De ClickHouse-exporter van de collector maakt de tabellen, otel_traces, otel_logs en één tabel per metrictype aan. De exporter past alleen een time to live toe als de configuratie in infra/collector/config.yaml dit instelt. Er verloopt niets automatisch. Een drukke maand kan de schijf daarom volledig vullen als u hier geen rekening mee houdt.

Installeren vanuit een vastgezette commit

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

git tag -l geeft vanaf 13 oktober 2026 niets weer. Kies de commit die u hebt getest en blijf daarop:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Daarna de toolchain:

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

package.json declareert engines.node als >=20.0.0 en packageManager als pnpm@9.12.0. Een incompatibele Node-versie stopt de installatie niet automatisch: het afdwingen van de engine-versie is afhankelijk van de configuratie, en pnpm 9.12.0 heeft een waarschuwingspad wanneer engineStrict is uitgeschakeld. Het pakket nodejs in het Ubuntu 24.04-archief is ouder dan 20. Installeer daarom Node 20 of nieuwer via NodeSource of nvm. De repository bevat een .nvmrc. nvm use kiest daardoor de bedoelde versie als u nvm gebruikt.

pnpm install
docker compose up -d
docker compose ps

Wacht op de healthchecks. Ga er niet van uit dat up -d betekent dat de service gereed is. Zowel Postgres als ClickHouse definieert hiervoor een controle in het compose-bestand:

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

ClickHouse reageert op Ok. en pg_isready reageert op accepting connections. Een geweigerde verbinding op 8123 betekent dat de container nog start of is gestopt. docker compose logs clickhouse laat zien welke situatie van toepassing is. docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled meldt true wanneer de kernel het proces wegens geheugengebrek heeft beëindigd. Dat wijst erop dat de server te klein is, niet op een fout in uw configuratie.

Daarna volgen de migratie en de applicaties:

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

Let op de poort: 5434, niet 5432. Het compose-bestand publiceert Postgres op 5434, zodat dit niet botst met een Postgres-installatie die al op de host draait. De .env.example-bestanden van de applicatie komen overeen met deze configuratie, met DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Richt de migratie op 5432 op een server waarop al Postgres draait. Dan krijgt u een geweigerde verbinding of, erger nog, wordt de migratie op de verkeerde database uitgevoerd.

pnpm dev voert turbo run dev uit. Daarmee wordt het dev-script van elke applicatie gestart via Turborepo, waaronder api, web, worker en proxy. De uitvoer wordt in één terminal gecombineerd. De Procfile van de repository vermeldt dezelfde vier processen en schrijft de uitvoer van elk proces door naar tmp/logs/. Start dit met een Procfile-runner zoals overmind of foreman in plaats van pnpm dev als u tail -f tmp/logs/proxy.log wilt gebruiken als plek om ingest te monitoren. Volgens de README draait de webapp op http://localhost:5173, de API op http://localhost:4100 en de OTLP-intake op http://localhost:4101.

Controleer wat daadwerkelijk aan een poort is gebonden voordat u er iets naartoe verwijst:

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

Dit is later belangrijk. De proxy leest zijn eigen poort uit de omgevingsvariabele PORT en gebruikt 4000 als terugvalwaarde wanneer PORT niet is ingesteld. De apps/proxy/.env.example die de proxy laadt, stelt ook PORT=4000 in, hoewel de README de intake op 4101 vermeldt. Beide waarden zijn gecontroleerd op 13 oktober 2026. Gebruik de poort die ss toont. De voorbeelden hieronder gebruiken 4101. Vervang die waarde door 4000 als de proxy op die poort luistert. Een systemd-unit die u zelf schrijft, stelt niets in tenzij u PORT daarin opneemt. Een exporter die naar 4101 verwijst terwijl de proxy op 4000 luistert, krijgt dan een geweigerde verbinding zonder verdere aanwijzing over de oorzaak.

Eén trace versturen, één fout veroorzaken, één incident zien

Maak een project in de webapp en kopieer de ingest key. De intake verifieert elk verzoek met deze key. Telemetrie zonder key bereikt ClickHouse daarom nooit.

Richt een OpenTelemetry SDK met de standaardomgevingsvariabelen op de intake:

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'

De intake leest de key uit de header x-api-key. Ook authorization: bearer YOUR_INGEST_KEY wordt geaccepteerd als uw exporter eenvoudiger op die manier kan worden geconfigureerd. De intake biedt de drie standaard-OTLP-paden /v1/traces, /v1/logs en /v1/metrics, plus /health.

Eén valkuil verdient extra aandacht. OTEL_EXPORTER_OTLP_ENDPOINT is een basis-URL waaraan de SDK het signaalpad toevoegt. Signaalspecifieke variabelen zoals OTEL_EXPORTER_OTLP_TRACES_ENDPOINT worden exact gebruikt zoals ze zijn opgegeven. Er wordt geen pad aan toegevoegd. Stel de signaalspecifieke variabele in op http://127.0.0.1:4101. Dan worden alle exports naar / gestuurd. Dat is geen route. Er komt dan niets aan en de SDK logt een exportfout, terwijl uw app gezond lijkt.

Voor een Node-service volstaat de codevrije route om de pipeline te testen:

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

Breek nu opzettelijk iets. Elke route die een fout genereert is geschikt:

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

Controleer de tussenstappen in volgorde. De eerste onderbreking laat zien welke stap is mislukt:

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

Een oplopende teller in otel_traces terwijl de webapp leeg blijft, wijst op een projectmismatch. Controleer daarom bij welk project de ingest key hoort. Een onveranderde teller met activiteit in het proxylog wijst op de collector of het schrijven naar ClickHouse. Lees dan docker compose logs collector. Geen enkele activiteit in het proxylog betekent dat de exporter de intake nooit heeft bereikt: de poort of het pad is verkeerd, of de key is geweigerd.

In de webapp komen deze herhaalde fouten als één incident binnen, niet als één rij per verzoek. Superlog maakt fingerprints van binnenkomende signalen en groepeert overeenkomende signalen. Daardoor bevat de inbox niet 4,000 identieke fouten, maar één pagina-item. De standaard community agent runner legt vervolgens lokaal een incidentsamenvatting voor die groep vast.

Voor een modelgestuurd onderzoek moeten een modelprovider en een compatibele agent runner zijn geconfigureerd. De standaard community runner legt een lokale samenvatting vast. Haal de namen van deze variabelen uit het bestand .env.example in elke app-directory van de commit die u hebt vastgezet, en niet uit een externe beschrijving. Deze namen veranderen namelijk mee met main. Hetzelfde geldt voor de GitHub- en Sentry-integraties. Deze hebben hun eigen installatiedocumentatie op docs/github-app-setup.md en docs/sentry-app-setup.md. De webhook-payloads zijn gedocumenteerd in docs/webhooks.md.

Houd de intake privé en maak de agent alleen-lezen

Docker publiceert containerpoorten standaard op 0.0.0.0, en die gepubliceerde poorten omzeilen ufw. Docker routeert containerverkeer in de nat-tabel. Daardoor wordt een pakket dat bestemd is voor een gepubliceerde poort omgeleid voordat het de ketens INPUT en OUTPUT bereikt, waarin de regels van ufw staan. ufw krijgt daar dus geen invloed op. Op een VPS met een openbaar IP-adres stelt het meegeleverde compose-bestand ClickHouse HTTP beschikbaar op 8123 en Postgres op 5434, waardoor ze vanaf internet bereikbaar zijn. De referenties in dat bestand zijn standaardwaarden voor ontwikkeling: ClickHouse-gebruiker default met een leeg wachtwoord, en Postgres met postgres als gebruikersnaam en wachtwoord.

Bind deze poorten aan loopback. Elke gepubliceerde poort in het compose-bestand haalt de hostzijde uit een omgevingsvariabele. Een .env in de hoofdmap van de repository is daarom voldoende:

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

Controleer het resultaat voordat u erop vertrouwt en maak de containers daarna opnieuw aan:

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

docker compose config geeft het opgeloste bestand weer, zodat u 127.0.0.1:5434:5432 kunt lezen in plaats van te moeten raden. ss moet daarna 127.0.0.1:5434 tonen en nooit 0.0.0.0:5434. Als u ports eenvoudig opnieuw definieert in een Compose-overridebestand, blijven beide bindings behouden wanneer het host-IP-adres verschilt. Compose 2.24.4 en hoger ondersteunt ports: !override om de lijst te vervangen.

De intake vereist dezelfde zorg. Uw ingest-key wordt in een header meegestuurd en vereist daarom TLS (transport layer security) ervoor: beëindig TLS in nginx of Caddy vóór de proxy, of houd ingest binnen een privénetwerk of een WireGuard-tunnel. De webapp op 5173 is een Vite-ontwikkelserver en mag helemaal niet vanaf internet bereikbaar zijn.

Daarna de agent zelf. De kern van Superlog is dat de agent een oplossing onderzoekt en voorstelt. Het belangrijke woord is: voorstelt. Houd de agent alleen-lezen ten opzichte van productie totdat u hebt gezien hoe deze op enkele echte incidenten werkt. Een alleen-lezen GitHub App kan geen fix branch pushen of pull requests openen. De installatiehandleiding vereist daarvoor schrijfrechten voor Contents en Pull requests, plus schrijfrechten voor Issues om opmerkingen te plaatsen. Een agent die telemetrie leest en een patch schrijft, is nuttig. Een agent die uw services kan herstarten, brengt een ander risiconiveau met zich mee. Dat moet u bewust beslissen en niet als standaardinstelling overnemen. Let bij het configureren van een modelgestuurde runner ook op de kosten: begroot de agentkosten op een VPS voordat u deze op een druk productiesysteem richt, en houd bij wat de agent daadwerkelijk heeft gedaan, zodat een onverwachte pull request een audittrail heeft.

Storingen die u tegenkomt en de meldingen waarmee ze worden aangeduid

  • ERR_PNPM_UNSUPPORTED_ENGINE tijdens pnpm install betekent dat een enginevereiste niet compatibel is. pnpm 9.12.0 controleert de vereisten voor zowel Node als pnpm. Lees de gewenste en huidige versies in de foutmelding en controleer daarna node -v en pnpm -v.
  • ECONNREFUSED 127.0.0.1:5434 tijdens de migratie betekent dat de Compose-stack niet actief is, of dat DATABASE_URL naar de verkeerde poort verwijst.
  • Controleer herstarts van ClickHouse met docker compose logs clickhouse. Controleer daarna in de container of OOMKilled true is.
  • Als een exporter succes meldt terwijl de webapp leeg blijft, is de data meestal rechtstreeks naar de collector op 4318 gestuurd. Daardoor wordt de projectidentificatie overgeslagen die de proxy toevoegt.
  • Een geweigerde verbinding op 4101 betekent meestal dat de proxy op 4000 luistert. Dat is de poort waarop de code terugvalt en die door .env.example wordt ingesteld. Stel PORT expliciet in het unitbestand of in .env van de app in.
  • Als docker compose ps 0.0.0.0:8123 toont, zijn de loopback-bindingen niet actief. Voer docker compose config uit en lees de opgeloste poorten.

Flawless, HyperProbe en de positie van Superlog

Deze categorie is nog jong. De tools verschillen in wat de agent mag aanraken. De Flawless-repository presenteert nu CISRE, een AI SRE-platform (site reliability engineering) voor Kubernetes en cloudinfrastructuur, onder de PolyForm Noncommercial-licentie. HyperProbe plaatst probes in een actief proces om de status van variabelen vast te leggen en stelt die status via MCP (model context protocol) beschikbaar aan een assistent. Het documenteert ook zelfhosting met Docker Compose en een licentiesleutel.

Superlog bevindt zich tussen beide. Het beheert de volledige pipeline, van OTLP-inname tot opslag in ClickHouse, en plaatst de agent bij de triage-stap in plaats van bij de herstelstap. Daarom is zelfhosting van Superlog een infrastructuurbeslissing en niet iets dat u als een vergeten container kunt beschouwen. Zodra u Superlog uitvoert, beheert u een column store. Die vereist dezelfde zorg als elke andere database die u zelf beheert.

FAQ

Hoeveel RAM heeft een zelfgehoste Superlog nodig?

Plan voor 8 GB RAM, 4 vCPU en 40 GB schijfruimte voor één node bij een laag ingestvolume. De stack bestaat uit Postgres, ClickHouse, een OpenTelemetry-collector en vier Node-processen, en ClickHouse verwacht extra capaciteitsruimte. Meet uw eigen waarden met docker stats --no-stream en free -m in plaats van een gepubliceerde waarde, waaronder deze, zonder meer te vertrouwen.

Naar welke poort moet ik mijn OTLP-exporter laten wijzen?

Naar de Superlog-intakeproxy, die de README op http://localhost:4101 configureert. Deze biedt /v1/traces, /v1/logs en /v1/metrics aan en verifieert met de ingest-key van uw project, die uit de x-api-key-header of uit een authorization: bearer-header wordt gehaald. Poort 4318 is de onderliggende OpenTelemetry-collector. Als u daar rechtstreeks naartoe exporteert, slaat u de proxy over. De proxy voegt juist uw project-id aan de gegevens toe. De proxy valt terug op poort 4000 wanneer PORT niet is ingesteld. De instelling .env.example gebruikt eveneens 4000. Voer daarom ss -lntp uit en controleer waarop de service heeft gebonden voordat u ervan uitgaat dat dit 4101 is.

Vervangt Superlog Uptime Kuma of Zabbix?

Nee. Uptime Kuma controleert van buiten uw netwerk of een endpoint reageert. Zabbix monitort host- en servicemetrics aan de hand van door u ingestelde drempelwaarden. Superlog verwerkt de traces, logs en metrics die uw applicaties produceren en groepeert herhaalde fouten in incidenten. Houd daarnaast een externe uptime-probe actief. Een probe die elders draait, meldt nog steeds wanneer de server waarop uw telemetriepipeline draait, de component is die is uitgevallen.

Kan de Superlog-agent mijn productiesystemen wijzigen?

Alleen met de rechten die u de agent verleent. De standaardrunner uit de community registreert een lokale incidentsamenvatting. Andere runtimes voor onderzoeken zijn afhankelijk van de runner die u configureert. Beperk productiecredentials tot leesrechten; voor het openen van pull requests zijn afzonderlijke GitHub-schrijfrechten voor branches en pull requests vereist. Behandel schrijftoegang tot productie als een afzonderlijke beslissing die u bewust neemt. Een agent die services kan herstarten, vraagt namelijk om een veel grotere betrokkenheid dan een agent die telemetrie leest en een patch schrijft die ter beoordeling kan worden voorgelegd.

Moet ik een commit vastzetten of main volgen?

Zet een commit vast. Op 13 oktober 2026 waren er geen releasetags in de repository. Leg de SHA vast die u hebt getest, implementeer die versie en lees de diff voordat u verdergaat. git log --oneline <old-sha>..main is de review. De .env.example-bestanden per app zijn de eerste plaats waar u na een upgrade moet zoeken naar nieuw vereiste variabelen.

Was dit artikel nuttig?