Superlog zelf hosten: installatie en werking

Wat Superlog bij self-hosting daadwerkelijk installeert

Om Superlog zelf te hosten, kloont 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 (OpenTelemetry protocol) traces, logs en metrieken naar een intake-poort. Superlog voorziet deze van een vingerafdruk, groepeert herhaalde items tot één incident en een agent schrijft de eerste aanzet voor de triage. De installatie kost een middag. De footprint en de eerlijke limieten zijn de onderdelen die u moet lezen voordat u begint.

Superlog is gelicentieerd onder Apache 2.0 en bevindt zich op github.com/superloglabs/superlog. Per augustus 2026 heeft het ongeveer 1.2k sterren, ruwweg 460 commits op main en helemaal geen release-tags. Dat laatste punt bepaalt de installatie: git checkout v1.0.0 heeft niets om uit te checken, dus u zet zelf een commit vast of u draait wat er op de ochtend van het klonen toevallig in main stond.

Wat Superlog beantwoordt wat Uptime Kuma en Langfuse niet doen

Zelfgehoste monitoringtools lijken van buitenaf inwisselbaar. Dat zijn ze niet, en het draaien van de verkeerde tool kost u een server zonder enig voordeel.

• Uptime Kuma test uw endpoints van buitenaf en beantwoordt één vraag: is het online.
• Zabbix bewaakt hosts en services op Ubuntu 24.04, met CPU, geheugen, schijfgebruik en servicestatus afgezet tegen door u ingestelde drempelwaarden.
• Langfuse traceert LLM-aanroepen, waarbij de prompt, het model, de tokens, de latentie en de kosten van elk verzoek worden vastgelegd.
• Superlog neemt de telemetrie die uw gewone services al verzenden en zet herhaalde fouten om in incidenten.

Superlog richt zich op een andere vraag: er is iets kapot, wat is er kapot en waarom. Het heeft geen mening over LLM-aanroepen en het test u niet van buitenaf. Het verwerkt OTLP vanuit uw normale applicatiecode en plaatst een agent bij de triage-stap; dit is de eerste controle die een menselijke operator tijdens een storingsdienst toch al zou uitvoeren.

Het onderscheid dat ertoe doet voor een VPS-budget is de opslag. Uptime Kuma draait prima op 1 GB RAM omdat het slechts enkele duizenden controleresultaten opslaat. Superlog bevat een kolomgeoriënteerde database, omdat telemetrie eenmalig wordt geschreven en vervolgens op tijdsbereik wordt bevraagd over miljoenen rijen. Dat is waar ClickHouse voor bedoeld is en waar Postgres niet voor is ontworpen. Postgres maakt nog steeds deel uit van de stack voor het opslaan van de kleine 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 per augustus 2026 geen productie-compose-bestand in de repository aanwezig, dus een langdurige installatie betekent dat u zelf systemd-units moet maken rondom het start-script van elke app, of de per-app Dockerfiles moet gebruiken die in de tree worden meegeleverd.

Houd het pad dat een span aflegt in gedachten, want elke onderstaande fout 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-sleutel, 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 verstrekte, 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 verwijderen van attributen is een essentiële controle voor multi-tenancy, geen decoratie. Zonder dit zou iedereen met een geldige ingest-sleutel 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 op één node bij een laag ingest-volume. Dit is een ondergrens voor de planning, geen exacte meting; beschouw dit als een startgrootte en toets dit aan uw eigen verkeer.

Het geheugen wordt op vier plaatsen gebruikt. ClickHouse is gebouwd voor machines met veel RAM en de standaardinstellingen gaan daarvan uit. Postgres 16 is hier bescheiden, aangezien het metadata bevat in plaats van telemetrie. De collector is eveneens bescheiden. De vier Node-processen zijn dat niet: een Vite-ontwikkelserver plus drie tsx watch-processen nemen elk honderden megabytes in beslag, wat de reden is waarom pnpm dev op een machine met 2 GB RAM moeizaam verloopt.

Schijfruimte is het minder opvallende probleem. pnpm install in deze monorepo haalt de AWS SDK, een ClickHouse-client, de OpenTelemetry SDK en een React-toolchain binnen voordat u ook maar één span heeft verwerkt. ClickHouse groeit vervolgens 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"

Bij een laag volume, waarbij een handvol services een paar honderd spans per minuut verstuurt, is de machine rustig en is ClickHouse het grootste deel van de tijd inactief. De belasting die voor problemen zorgt, is de piek: één foutieve deploy die duizenden identieke fouten per minuut genereert. Fingerprinting brengt deze terug tot één incident voor de gebruiker, maar ClickHouse schrijft nog steeds elke rij weg.

Retentie bepaalt u zelf. De ClickHouse-exporter van de collector maakt de tabellen otel_traces, otel_logs en één tabel per metriektype aan, en past alleen een 'time to live' toe als de configuratie in infra/collector/config.yaml er een instelt. Niets verloopt automatisch, dus een drukke maand resulteert in een volle schijf als u hier geen rekening mee houdt.

Installatie vanaf een specifieke commit

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

git tag -l Niets printen is het verwachte resultaat sinds augustus 2026. Kies de commit die u heeft getest en blijf daarbij:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Vervolgens 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. Voer de installatie uit op een oudere Node en pnpm stopt met ERR_PNPM_UNSUPPORTED_ENGINE, waarbij de gewenste versie wordt genoemd. Het nodejs-pakket in het Ubuntu 24.04-archief is ouder dan 20, dus installeer Node 20 of nieuwer via NodeSource of nvm. De repository bevat een .nvmrc, dus nvm use kiest de beoogde versie als u nvm gebruikt.

pnpm install
docker compose up -d
docker compose ps

Wacht op de health checks in plaats van erop te vertrouwen dat up -d betekent dat de service gereed is. Zowel Postgres als ClickHouse declareren er een 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 antwoordt met Ok. en pg_isready antwoordt met accepting connections. Connection refused op 8123 betekent dat de container nog aan het opstarten is of is gestopt. docker compose logs clickhouse laat zien wat het geval is, en docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled rapporteert true wanneer de kernel het proces heeft beëindigd vanwege geheugengebrek; dit wijst erop dat de server te klein is in plaats van op een fout in uw configuratie.

Vervolgens 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 het niet botst met een Postgres die al op de host is geïnstalleerd, en de .env.example-bestanden van de app komen overeen, met DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Richt de migratie op 5432 op een server die al Postgres draait en u krijgt ofwel een geweigerde verbinding of, erger nog, een migratie die op de verkeerde database wordt toegepast.

pnpm dev start de vier processen die in de Procfile van de repository worden vermeld: api, web, worker en proxy. Elk proces stuurt zijn output naar tmp/logs/, dus tail -f tmp/logs/proxy.log is de plek waar u de ingest kunt monitoren. De README plaatst de web-app op http://localhost:5173, de API op http://localhost:4100 en de OTLP-inname op http://localhost:4101.

Controleer wat er daadwerkelijk is gebonden voordat u er iets naar verwijst:

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

Dit is later van belang. De proxy leest zijn eigen poort uit de PORT omgevingsvariabele en valt terug op 4000 wanneer PORT niet is ingesteld. De development-stack stelt dit voor u in. Een systemd-unit die u zelf schrijft doet dit niet, waardoor een exporter die gericht is op 4101 tegen een proxy die op 4000 luistert, faalt met connection refused zonder verdere aanwijzingen.

Verstuur één trace, genereer één fout, zie één incident

Maak een project aan in de webapplicatie en kopieer de ingest key. De intake verifieert elk verzoek aan de hand van deze sleutel; telemetrie die zonder sleutel wordt verzonden, bereikt ClickHouse nooit.

Wijs een OpenTelemetry SDK naar de intake met behulp van de standaard omgevingsvariabelen:

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 sleutel uit de x-api-key header en accepteert ook authorization: bearer YOUR_INGEST_KEY als uw exporter op die manier eenvoudiger te configureren is. De intake bedient de drie standaard OTLP-paden, /v1/traces, /v1/logs en /v1/metrics, plus /health.

Eén valkuil is het benoemen waard. OTEL_EXPORTER_OTLP_ENDPOINT is een basis-URL en de SDK voegt daar het signaalpad aan toe. De signaalspecifieke variabelen zoals OTEL_EXPORTER_OTLP_TRACES_ENDPOINT worden exact gebruikt zoals geschreven, zonder toegevoegd pad. Stel de signaalspecifieke variabele in op http://127.0.0.1:4101 en elke export wordt gepost naar /. Dit is geen geldige route, waardoor er niets aankomt en de SDK een exportfout logt terwijl uw applicatie gezond lijkt.

Voor een Node-service is het zero-code pad voldoende om de pipeline te valideren:

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

Forceer nu opzettelijk een fout. Elke route die een exception gooit, volstaat:

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

Controleer de hops in volgorde, want het eerste gat geeft aan waar het misging:

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

Een stijgend aantal in otel_traces bij een lege webapplicatie duidt op een project-mismatch; controleer dus bij welk project de ingest key hoort. Een gelijkblijvend aantal met activiteit in het proxy-logboek wijst op de collector of de ClickHouse-schrijfactie; raadpleeg daarom docker compose logs collector. Geen enkele activiteit in het proxy-logboek betekent dat de exporter de intake nooit heeft bereikt: verkeerde poort, verkeerd pad of een geweigerde sleutel.

In de webapplicatie komen deze herhaalde fouten binnen als één incident in plaats van één rij per verzoek. Superlog maakt vingerafdrukken van inkomende signalen en groepeert overeenkomstige signalen. Dit is het verschil tussen een inbox met 4.000 identieke fouten en een pagina met één incident. De agent schrijft vervolgens zijn onderzoek boven op die groep.

De onderzoeksstap roept een model aan, dus de worker heeft een geconfigureerde modelprovider nodig. Neem de variabelenamen uit het .env.example-bestand in elke app-directory van de commit die u heeft vastgezet, in plaats van uit externe documentatie, omdat deze wijzigen met main. Hetzelfde geldt voor de GitHub- en Sentry-integraties, die hun eigen setup-documenten bevatten op docs/github-app-setup.md en docs/sentry-app-setup.md, met webhook-payloads gedocumenteerd in docs/webhooks.md.

Houd de intake privé en de agent alleen-lezen

Docker publiceert containerpoorten standaard op 0.0.0.0. Deze gepubliceerde poorten omzeilen ufw, omdat Docker eigen regels schrijft naar de DOCKER-USER-chain die worden geëvalueerd voordat ufw het pakket ziet. Op een VPS met een publiek IP-adres stelt het meegeleverde compose-bestand ClickHouse HTTP in op 8123 en Postgres op 5434, waardoor ze bereikbaar zijn vanaf het internet. De inloggegevens in dat bestand zijn standaardwaarden voor ontwikkeling: ClickHouse-gebruiker default met een leeg wachtwoord, en Postgres met postgres als zowel gebruiker als wachtwoord.

Bind deze aan de loopback. Elke gepubliceerde poort in het compose-bestand haalt de host-zijde uit een omgevingsvariabele, dus een .env in de root van de repository volstaat:

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 het 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 toont het opgeloste bestand, zodat u 127.0.0.1:5434:5432 kunt lezen in plaats van te gissen. ss zou daarna 127.0.0.1:5434 moeten tonen en nooit 0.0.0.0:5434. Probeer dit niet op te lossen met een compose-override-bestand dat ports opnieuw declareert, omdat Compose poortlijsten in bestanden samenvoegt in plaats van ze te vervangen. Hierdoor eindigt u met beide bindingen en blijft de publieke poort alsnog openstaan.

De intake vereist dezelfde zorgvuldigheid. Uw ingest-sleutel wordt verstuurd in een header, dus deze heeft TLS (transport layer security) nodig: beëindig TLS in nginx of Caddy vóór de proxy, of houd ingest binnen een privénetwerk of een WireGuard-tunnel. De web-app op 5173 is een Vite-ontwikkelingsserver en hoort in het geheel niet direct aan het internet te hangen.

Dan de agent zelf. De insteek van Superlog is dat de agent onderzoek doet en een oplossing voorstelt; het belangrijkste woord hierbij is voorstelt. Houd de agent alleen-lezen ten opzichte van productie totdat u hebt gezien hoe deze werkt bij een aantal echte incidenten. Geef de GitHub App alleen-lezen-rechten en laat deze pull requests openen die u vervolgens beoordeelt. 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; dit moet een bewuste beslissing zijn en geen standaardinstelling die u overneemt. Kosten verdienen dezelfde aandacht, aangezien elk onderzoek een model-aanroep is: budget voor agent-uitgaven op een VPS voordat u deze inzet op een druk productiesysteem, en houd een logboek bij van wat de agent daadwerkelijk heeft gedaan zodat een verrassend pull request altijd een audit-spoor heeft.

Veelvoorkomende fouten en de bijbehorende foutmeldingen

• ERR_PNPM_UNSUPPORTED_ENGINE tijdens pnpm install betekent dat de Node-versie ouder is dan 20. node -v bevestigt dit in één regel.
• 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.
• Als ClickHouse in een lus blijft herstarten, is er meestal sprake van een geheugenprobleem. Lees docker compose logs clickhouse en controleer vervolgens de container op OOMKilled met de waarde true.
• Een exporter die succes rapporteert terwijl de webapplicatie leeg blijft, betekent meestal dat de data rechtstreeks naar de collector op 4318 is verzonden, waardoor de projectstempel van de proxy wordt overgeslagen.
• Connection refused op 4101 bij een productie-installatie betekent dat de proxy is teruggevallen op PORT=4000. Stel PORT expliciet in het unit-bestand in.
• docker compose ps met de melding 0.0.0.0:8123 betekent dat uw loopback-bindings niet actief zijn. Voer docker compose config uit en controleer de opgeloste poorten.

Flawless, HyperProbe en de positie van Superlog

Deze categorie is nog jong en de tools verschillen van mening over wat de agent mag aanpassen. Flawless is een open source AI SRE-tool (site reliability engineering) gericht op Kubernetes. Deze tool leest gegevens uit een bestaande Prometheus-, Loki- en Grafana-stack in plaats van de pipeline zelf te beheren. HyperProbe kiest de tegenovergestelde route: het is een gehost product, dat per augustus 2026 closed source is, en dat read-only probes in een draaiend proces plaatst om de variabele status vast te leggen en deze status via MCP (model context protocol) aan een assistent aan te bieden.

Superlog bevindt zich tussen deze twee in. 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. Dat ontwerp is precies de reden waarom self-hosting hiervan een infrastructurele beslissing is en niet zomaar een container die u kunt vergeten. Zodra u Superlog draait, draait u een column store, en deze vereist hetzelfde onderhoud als elke andere database die u beheert.

FAQ

Hoeveel RAM heeft een zelfgehoste Superlog nodig?

Houd rekening met 8 GB RAM, 4 vCPU en 40 GB schijfruimte voor een enkele node bij een laag volume aan inkomende data. De stack bestaat uit Postgres, ClickHouse, een OpenTelemetry collector en vier Node-processen; ClickHouse vereist extra vrije ruimte. Een VPS met 1 GB of 2 GB is onvoldoende: pnpm install is op zichzelf al zwaar en ClickHouse wordt onder belasting door de kernel out-of-memory killer beëindigd. Meet uw eigen waarden met docker stats --no-stream en free -m in plaats van te vertrouwen op gepubliceerde cijfers, inclusief deze.

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

Naar de Superlog intake proxy, die in de README op http://localhost:4101 staat. Deze bedient /v1/traces, /v1/logs en /v1/metrics en authenticeert met de ingest-sleutel van uw project, afkomstig uit de x-api-key-header of een authorization: bearer-header. Poort 4318 is de onderliggende OpenTelemetry collector; direct exporteren naar deze poort omzeilt de proxy, de component die uw project-id aan de data toevoegt. De proxy valt terug op poort 4000 wanneer PORT niet is ingesteld. Voer daarom ss -lntp uit en controleer waaraan de service is gebonden voordat u uitgaat van 4101.

Vervangt Superlog Uptime Kuma of Zabbix?

Nee. Uptime Kuma beantwoordt de vraag of een endpoint reageert van buiten uw netwerk, en Zabbix bewaakt host- en servicemetrics op basis van door u ingestelde drempelwaarden. Superlog verwerkt de traces, logs en metrics die uw applicaties genereren en groepeert herhaalde fouten in incidenten. Gebruik daarnaast een externe uptime-probe, omdat een probe die elders draait nog steeds rapporteert wanneer de server met uw telemetrie-pipeline uitvalt.

Kan de Superlog-agent mijn productiesystemen wijzigen?

Alleen via de rechten die u verleent. De output is een onderzoek en een voorgestelde wijziging die door een mens wordt beoordeeld. Houd de GitHub App in eerste instantie op leesrechten met pull requests en beperk de credentials van de worker tot leesrechten. Beschouw schrijftoegang tot productie als een afzonderlijke, weloverwogen beslissing; een agent die services kan herstarten is een grotere verantwoordelijkheid dan een agent die telemetrie leest en een patch schrijft voor beoordeling.

Moet ik een commit vastzetten of de main-branch volgen?

Zet een commit vast. Er zijn per augustus 2026 geen release-tags in de repository, dus main is het enige bewegende doelwit en deze ontvangt wekelijks meerdere commits. Noteer de SHA die u heeft getest, implementeer die versie en lees de diff door voordat u verdergaat. git log --oneline <old-sha>..main bevat de beoordeling en de .env.example-bestanden per applicatie zijn de eerste plek om te controleren op nieuw vereiste variabelen na een update.