Superlog selbst hosten: Ressourcen und Grenzen

Was Self-Hosting von Superlog tatsächlich installiert

Für das Self-Hosting von Superlog klonen Sie das Repository, starten Postgres, ClickHouse und einen OpenTelemetry-Collector mit Docker Compose, führen eine Datenbankmigration aus und starten anschließend vier Node-Dienste aus dem Quellcode. Ihre Anwendungen senden OTLP-Traces, -Logs und -Metriken an einen Intake-Port. Superlog erstellt daraus Fingerprints, fasst wiederkehrende Ereignisse zu einem einzelnen Incident zusammen und ein Agent erstellt eine erste Triage. Die Installation dauert einen Nachmittag. Der Ressourcenbedarf und die tatsächlichen Einschränkungen sind die Punkte, die Sie vor dem Start lesen sollten.

Superlog steht unter der Apache-2.0-Lizenz und befindet sich unter github.com/superloglabs/superlog. Im August 2026 hat das Projekt rund 1.2k Sterne, ungefähr 460 Commits auf main und überhaupt keine Release-Tags. Dieser letzte Punkt prägt die Installation: git checkout v1.0.0 enthält nichts, das Sie auschecken können. Sie müssen daher selbst einen Commit festlegen oder verwenden, was sich am Morgen Ihres Klonens zufällig auf main befand.

Welche Fragen Superlog beantwortet, die Uptime Kuma und Langfuse nicht beantworten

Self-hosted-Monitoring-Tools wirken von außen austauschbar. Das sind sie nicht. Der Einsatz des falschen Tools kostet Sie einen Server, ohne einen Nutzen zu bringen.

• Uptime Kuma prüft Ihre Endpunkte von außen und beantwortet eine Frage: Ist der Dienst erreichbar?
• Zabbix überwacht Hosts und Dienste unter Ubuntu 24.04 und vergleicht CPU, Arbeitsspeicher, Datenträger und Dienststatus mit den von Ihnen festgelegten Schwellenwerten.
• Langfuse verfolgt LLM-Aufrufe und erfasst für jeden Aufruf den Prompt, das Modell, die Token, die Latenz und die Kosten.
• Superlog übernimmt die Telemetriedaten, die Ihre normalen Dienste bereits ausgeben, und wandelt wiederkehrende Fehler in Incidents um.

Superlog beantwortet eine andere Frage: Etwas ist ausgefallen. Was ist ausgefallen und warum? Das Tool bewertet keine LLM-Aufrufe und prüft Ihr System nicht von außen. Es nimmt OTLP aus Ihrem normalen Anwendungscode entgegen und setzt einen Agenten bei der Triage ein. Das entspricht dem ersten Prüfschritt, den ein Bereitschaftstechniker ohnehin durchführen würde.

Für das Budget eines VPS ist der Speicherbedarf entscheidend. Uptime Kuma läuft problemlos mit 1 GB RAM, weil es einige tausend Prüfergebnisse speichert. Superlog verwendet einen Column Store, weil Telemetriedaten einmal geschrieben und anschließend über Zeitbereiche hinweg aus Millionen von Zeilen abgefragt werden. Dafür ist ClickHouse vorgesehen, nicht Postgres. Postgres bleibt Bestandteil des Stacks und speichert die wenigen relationalen Daten: Projekte, Benutzer, Incidents und Ingest-Schlüssel.

Was startet docker compose up -d tatsächlich?

Drei Container, und keiner davon ist Superlog. Das überrascht viele, die eine Installation mit einem einzigen Befehl erwarten.

• postgres:16, veröffentlicht auf dem Host-Port 5434
• clickhouse/clickhouse-server:26.1, auf Port 8123 für HTTP und 9000 für das native Protokoll
• otel/opentelemetry-collector-contrib:0.150.1, auf Port 4317 für gRPC und 4318 für OTLP über HTTP

Die Superlog-Anwendungen laufen auf dem Host aus dem Quellcode und werden von pnpm dev gestartet. Im Repository gibt es seit August 2026 keine Compose-Datei für den Produktivbetrieb. Für einen dauerhaft laufenden Betrieb benötigen Sie daher eigene systemd-Units für die start-Skripte der einzelnen Anwendungen oder die Dockerfiles der jeweiligen Anwendungen im Repository.

Behalten Sie den Pfad im Blick, den ein Span nimmt, denn jeder Fehler weiter unten ist eine Unterbrechung in einem seiner Abschnitte. Ihre Anwendung sendet OTLP an den Superlog-Intake-Proxy. Der Proxy authentifiziert die Anfrage mit Ihrem Ingest-Key, versieht sie mit der Projekt-ID und leitet sie an den Collector weiter. Der Collector entfernt alle superlog.*-Attribute, die der Client zu setzen versucht hat, ergänzt superlog.project_id aus dem Header, den der Proxy bereitgestellt hat, bündelt die Daten und schreibt sie in ClickHouse. Die Webanwendung und die API lesen die Telemetriedaten anschließend aus ClickHouse. Alle übrigen Daten lesen sie aus Postgres.

Das Entfernen dieser Attribute ist eine echte Maßnahme zur Mandantentrennung und keine reine Dekoration. Ohne diese Maßnahme könnte jeder mit einem gültigen Ingest-Key superlog.project_id selbst setzen und Daten in das Projekt eines anderen Mandanten schreiben.

Wie groß muss der VPS sein?

Planen Sie für eine Single-Node-Installation bei geringem Ingest-Volumen mit 4 vCPU, 8 GB RAM und 40 GB SSD. Das ist eine Planungsuntergrenze, keine Messung. Betrachten Sie diese Größe daher als Ausgangspunkt und prüfen Sie sie anhand Ihres eigenen Datenverkehrs.

Der Arbeitsspeicher verteilt sich auf vier Bereiche. ClickHouse ist für Systeme mit viel RAM ausgelegt, und die Standardwerte gehen davon aus. Postgres 16 ist in diesem Fall genügsam, da es Metadaten und keine Telemetriedaten speichert. Auch der Collector benötigt vergleichsweise wenig Speicher. Das gilt nicht für die vier Node-Prozesse: Ein Vite-Entwicklungsserver und drei tsx watch-Prozesse belegen jeweils mehrere hundert Megabyte. Deshalb ist pnpm dev auf einem System mit 2 GB RAM problematisch.

Der Speicherplatz ist das weniger auffällige Problem. pnpm install in diesem Monorepo lädt das AWS SDK, einen ClickHouse-Client, das OpenTelemetry SDK und eine React-Toolchain, bevor Sie auch nur einen einzigen Span ingestiert haben. ClickHouse wächst anschließend mit Ihrem Datenverkehr. Messen Sie beides:

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"

Bei geringem Volumen ist das System ruhig, wenn eine Handvoll Dienste einige hundert Spans pro Minute sendet, und ClickHouse ist die meiste Zeit untätig. Belastend sind Spitzen: Ein fehlerhaftes Deployment kann pro Minute Tausende identische Fehler erzeugen. Das Fingerprinting fasst diese Fehler für den Leser zu einem Incident zusammen. ClickHouse schreibt jedoch weiterhin jede einzelne Zeile.

Die Aufbewahrungsdauer legen Sie selbst fest. Der ClickHouse-Exporter des Collectors erstellt die Tabellen otel_traces, otel_logs und jeweils eine Tabelle pro Metriktyp. Eine automatische Löschung nach Ablauf einer bestimmten Zeit wird nur aktiviert, wenn die Konfiguration in infra/collector/config.yaml eine entsprechende Einstellung enthält. Ohne diese Einstellung läuft nichts automatisch ab. Ein stark ausgelasteter Monat kann daher die gesamte Festplatte füllen, wenn Sie dies nicht einplanen.

Install from a pinned commit

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

git tag -l printing nothing is the expected result as of August 2026. Pick the commit you tested and stay on it:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Next, the toolchain:

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

package.json declares engines.node as >=20.0.0 and packageManager as pnpm@9.12.0. Run the install on an older Node and pnpm stops with ERR_PNPM_UNSUPPORTED_ENGINE, naming the version it wanted. The nodejs package in the Ubuntu 24.04 archive is older than 20, so install Node 20 or newer from NodeSource or from nvm. The repository ships an .nvmrc, so nvm use picks the intended version if you have nvm.

pnpm install
docker compose up -d
docker compose ps

Wait for the health checks instead of trusting up -d to mean ready. Postgres and ClickHouse both declare one in the compose file:

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

ClickHouse answers Ok. and pg_isready answers accepting connections. Connection refused on 8123 means the container is still starting or has died. docker compose logs clickhouse shows which, and docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled reports true when the kernel killed it for memory, which points at the box being too small rather than at your config.

Then the migration and the applications:

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

Note the port: 5434, not 5432. The compose file publishes Postgres on 5434 so it does not collide with a Postgres already installed on the host, and the app .env.example files match, with DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Point the migration at 5432 on a box that already runs Postgres and you either get a refused connection or, worse, a migration applied to the wrong database.

pnpm dev starts the four processes listed in the repository's Procfile: api, web, worker and proxy. Each tees its output into tmp/logs/, so tail -f tmp/logs/proxy.log is where you watch ingest. The README puts the web app on http://localhost:5173, the API on http://localhost:4100 and the OTLP intake on http://localhost:4101.

Confirm what actually bound before you point anything at it:

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

This matters later. The proxy reads its own port from the PORT environment variable and falls back to 4000 when PORT is unset. The development stack sets it for you. A systemd unit you write yourself does not, so an exporter aimed at 4101 against a proxy listening on 4000 fails with connection refused and gives you no other clue.

Einen Trace senden, einen Fehler erzeugen, einen Incident sehen

Erstellen Sie in der Webanwendung ein Projekt und kopieren Sie dessen Ingest-Key. Die Intake authentifiziert jede Anfrage anhand dieses Keys. Telemetrie ohne diesen Key erreicht ClickHouse daher nie.

Verweisen Sie ein beliebiges OpenTelemetry-SDK über die standardmäßigen Umgebungsvariablen auf die 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'

Die Intake liest den Key aus dem Header x-api-key. Sie akzeptiert auch authorization: bearer YOUR_INGEST_KEY, wenn sich Ihr Exporter auf diese Weise leichter konfigurieren lässt. Sie stellt die drei standardmäßigen OTLP-Pfade /v1/traces, /v1/logs und /v1/metrics sowie /health bereit.

Ein häufiger Fehler ist erwähnenswert. OTEL_EXPORTER_OTLP_ENDPOINT ist eine Basis-URL. Das SDK hängt den Pfad des jeweiligen Signals daran an. Signalspezifische Variablen wie OTEL_EXPORTER_OTLP_TRACES_ENDPOINT werden genau wie angegeben verwendet. Es wird kein Pfad angehängt. Setzen Sie die signalspezifische Variable auf http://127.0.0.1:4101, sendet jeder Export an /. Das ist keine Route. Daher kommt nichts an, und das SDK protokolliert einen Exportfehler, während Ihre Anwendung scheinbar fehlerfrei läuft.

Bei einem Node-Dienst genügt der codefreie Pfad, um die Pipeline zu überprüfen:

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

Lösen Sie nun absichtlich einen Fehler aus. Jede Route, die eine Exception auslöst, ist geeignet:

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

Prüfen Sie die Stationen in dieser Reihenfolge. Die erste Lücke zeigt, welche Station ausgefallen ist:

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

Ein steigender Zähler in otel_traces bei gleichzeitig leerer Webanwendung weist auf eine Projektverwechslung hin. Prüfen Sie daher, zu welchem Projekt der Ingest-Key gehört. Ein unveränderter Zähler bei Aktivität im Proxy-Log weist auf den Collector oder das Schreiben nach ClickHouse hin. Lesen Sie in diesem Fall docker compose logs collector. Gibt es im Proxy-Log überhaupt keine Aktivität, hat der Exporter die Intake nicht erreicht: falscher Port, falscher Pfad oder abgelehnter Key.

In der Webanwendung erscheinen diese wiederholten Fehler als ein Incident und nicht als eine Zeile pro Anfrage. Superlog erstellt Fingerprints für eingehende Signale und gruppiert übereinstimmende Signale. Dadurch enthält der Posteingang nicht 4,000 identische Fehler, sondern nur einen Eintrag. Der Agent schreibt seine Untersuchung anschließend auf dieser Gruppe auf.

Für den Untersuchungsschritt wird ein Modell aufgerufen. Daher muss für den Worker ein Model Provider konfiguriert sein. Übernehmen Sie die Namen dieser Variablen aus der Datei .env.example im jeweiligen App-Verzeichnis des von Ihnen angepinnten Commits und nicht aus einer externen Anleitung. Die Variablen ändern sich zusammen mit main. Das Gleiche gilt für die GitHub- und Sentry-Integrationen. Sie enthalten eigene Einrichtungsdokumente unter docs/github-app-setup.md und docs/sentry-app-setup.md. Webhook-Payloads sind unter docs/webhooks.md dokumentiert.

Eingang privat halten und den Agenten mit Leseberechtigung betreiben

Docker veröffentlicht Container-Ports standardmäßig auf 0.0.0.0. Diese veröffentlichten Ports umgehen ufw, weil Docker eigene Regeln in die Kette DOCKER-USER schreibt, die ausgewertet werden, bevor ufw das Paket sieht. Auf einem VPS mit öffentlicher IP veröffentlicht die mitgelieferte Compose-Datei ClickHouse HTTP auf 8123 und Postgres auf 5434, sodass beide Dienste aus dem Internet erreichbar sind. Die Zugangsdaten in dieser Datei sind Entwicklungsstandards: der ClickHouse-Benutzer default mit leerem Passwort sowie Postgres mit postgres als Benutzer und Passwort.

Binden Sie die Ports an das Loopback-Interface. Jeder veröffentlichte Port in der Compose-Datei bezieht die Host-Seite aus einer Umgebungsvariablen. Daher genügt eine .env im Stammverzeichnis des Repositorys:

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

Prüfen Sie das Ergebnis, bevor Sie darauf vertrauen, und erstellen Sie die Container anschließend neu:

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

docker compose config gibt die aufgelöste Datei aus. Dadurch können Sie 127.0.0.1:5434:5432 ablesen, statt zu raten. ss sollte anschließend 127.0.0.1:5434 anzeigen und niemals 0.0.0.0:5434. Versuchen Sie nicht, dieses Problem mit einer Compose-Override-Datei zu beheben, die ports erneut deklariert. Compose führt Portlisten aus mehreren Dateien zusammen, statt sie zu ersetzen. Dadurch erhalten Sie beide Bindings, und der öffentliche Port bleibt weiterhin geöffnet.

Auch der Eingang erfordert entsprechende Sorgfalt. Ihr Ingest-Key wird in einem Header übertragen. Daher benötigt er TLS (Transport Layer Security) davor: Beenden Sie TLS in nginx oder Caddy vor dem Proxy, oder halten Sie den Ingest innerhalb eines privaten Netzwerks oder eines WireGuard-Tunnels. Die Webanwendung auf 5173 ist ein Vite-Entwicklungsserver und darf keinesfalls aus dem Internet erreichbar sein.

Nun zum Agenten selbst. Superlog wirbt damit, dass der Agent Untersuchungen durchführt und eine Lösung vorschlägt. Entscheidend ist dabei das Wort „vorschlägt“. Betreiben Sie ihn in Produktionsumgebungen zunächst nur mit Leseberechtigung, bis Sie ihn bei einigen realen Vorfällen beobachtet haben. Geben Sie der GitHub App Leseberechtigungen und erlauben Sie ihr, Pull Requests zu öffnen, die Sie prüfen. Ein Agent, der Telemetriedaten liest und einen Patch erstellt, ist nützlich. Ein Agent, der Ihre Dienste neu starten kann, stellt ein anderes Risikoniveau dar. Das sollte eine bewusste Entscheidung sein und keine standardmäßig übernommene Berechtigung. Auch die Kosten erfordern Aufmerksamkeit, da jede Untersuchung einen Modellaufruf auslöst: kalkulieren Sie die Agentenkosten auf einem VPS bevor Sie ihn auf ein unruhiges Produktionssystem ansetzen, und führen Sie ein Protokoll über die tatsächlichen Aktionen des Agenten, damit ein unerwarteter Pull Request anhand eines Prüfpfads nachvollziehbar bleibt.

Fehler, auf die Sie stoßen werden, und die Zeichenfolgen, die sie benennen

• ERR_PNPM_UNSUPPORTED_ENGINE während pnpm install bedeutet, dass Node älter als 20 ist. node -v bestätigt dies in einer Zeile.
• ECONNREFUSED 127.0.0.1:5434 während der Migration bedeutet, dass der Compose-Stack nicht läuft oder DATABASE_URL den falschen Port angibt.
• Wenn ClickHouse in einer Schleife neu gestartet wird, liegt das normalerweise am Speicher. Lesen Sie docker compose logs clickhouse und prüfen Sie anschließend im Container, ob OOMKilled den Wert true hat.
• Wenn ein Exporter Erfolg meldet, die Webanwendung aber leer bleibt, wurden die Daten normalerweise direkt an den Collector auf Port 4318 gesendet. Dabei wird die Projektzuordnung übersprungen, die der Proxy vornimmt.
• Wird bei einer produktiven Installation die Verbindung auf Port 4101 abgelehnt, ist der Proxy auf PORT=4000 zurückgefallen. Setzen Sie PORT ausdrücklich in der Unit-Datei.
• Wenn docker compose ps 0.0.0.0:8123 anzeigt, sind Ihre Loopback-Bindings nicht wirksam. Führen Sie docker compose config aus und lesen Sie die aufgelösten Ports ab.

Flawless, HyperProbe und die Position von Superlog

Diese Kategorie ist noch jung, und die Tools unterscheiden sich darin, worauf der Agent zugreifen darf. Flawless ist ein Open-Source-KI-SRE-Tool (Site Reliability Engineering) für Kubernetes. Es liest Daten aus einem vorhandenen Prometheus-, Loki- und Grafana-Stack, statt die Pipeline selbst zu verwalten. HyperProbe verfolgt den umgekehrten Ansatz: Im August 2026 ist es ein gehostetes Produkt mit geschlossenem Quellcode. Es platziert schreibgeschützte Probes in einem laufenden Prozess, um den Variablenzustand zu erfassen, und stellt diesen Zustand einem Assistenten über MCP (Model Context Protocol) bereit.

Superlog liegt zwischen diesen beiden Ansätzen. Es verwaltet die gesamte Pipeline, von der OTLP-Annahme bis zur Speicherung in ClickHouse. Den Agenten setzt es beim Triage-Schritt ein, nicht beim Beheben des Problems. Genau deshalb ist das Self-Hosting eine Infrastrukturentscheidung und kein Container, den man nach der Einrichtung vergessen kann. Sobald Sie Superlog betreiben, betreiben Sie einen Column Store. Er benötigt dieselbe Pflege wie jede andere Datenbank in Ihrer eigenen Infrastruktur.

FAQ

Wie viel RAM benötigt ein selbst gehostetes Superlog?

Planen Sie für einen einzelnen Knoten bei geringem Ingest-Volumen 8 GB RAM, 4 vCPU und 40 GB Speicherplatz ein. Der Stack besteht aus Postgres, ClickHouse, einem OpenTelemetry-Collector und vier Node-Prozessen. ClickHouse benötigt außerdem ausreichend Reserve. Ein VPS mit 1 GB oder 2 GB RAM reicht nicht aus: Allein pnpm install benötigt viele Ressourcen, und ClickHouse wird unter Last vom OOM-Killer des Kernels beendet. Ermitteln Sie Ihre eigenen Werte mit docker stats --no-stream und free -m, statt einer veröffentlichten Angabe zu vertrauen, auch nicht dieser.

Auf welchen Port muss mein OTLP-Exporter zeigen?

Auf den Intake-Proxy von Superlog, der in der README unter http://localhost:4101 angegeben ist. Er stellt /v1/traces, /v1/logs und /v1/metrics bereit und authentifiziert sich mit dem Ingest-Schlüssel Ihres Projekts, der aus dem Header x-api-key oder einem Header authorization: bearer stammt. Port 4318 gehört zum darunterliegenden OpenTelemetry-Collector. Wenn Sie Daten direkt dorthin exportieren, umgehen Sie den Proxy. Dieser versieht die Daten mit der Projekt-ID. Wenn PORT nicht gesetzt ist, verwendet der Proxy Port 4000. Führen Sie daher ss -lntp aus und prüfen Sie, an welchen Port der Proxy gebunden ist, bevor Sie 4101 annehmen.

Ersetzt Superlog Uptime Kuma oder Zabbix?

Nein. Uptime Kuma prüft, ob ein Endpunkt von außerhalb Ihres Netzwerks antwortet. Zabbix überwacht Host- und Dienstmetriken anhand von Schwellenwerten, die Sie festlegen. Superlog verarbeitet die von Ihren Anwendungen erzeugten Traces, Logs und Metriken und fasst wiederkehrende Fehler zu Incidents zusammen. Betreiben Sie zusätzlich einen externen Uptime-Test. Ein Test, der an einem anderen Standort läuft, meldet weiterhin, wenn der Server mit Ihrer Telemetrie-Pipeline selbst ausfällt.

Kann der Superlog-Agent meine Produktionssysteme ändern?

Nur über die Berechtigungen, die Sie ihm erteilen. Seine Ausgabe besteht aus einer Untersuchung und einer vorgeschlagenen Änderung, die ein Mensch prüft. Beschränken Sie die GitHub App zunächst auf Leseberechtigungen und Pull Requests. Begrenzen Sie außerdem alle Zugangsdaten, die der Worker verwendet, auf Lesezugriff. Behandeln Sie Schreibzugriff auf die Produktion als separate, bewusste Entscheidung. Ein Agent, der Dienste neu starten kann, stellt eine deutlich größere Verpflichtung dar als ein Agent, der Telemetrie liest und einen Patch zur Prüfung erstellt.

Sollte ich einen Commit festlegen oder main verfolgen?

Legen Sie einen Commit fest. Im Repository gibt es mit Stand August 2026 keine Release-Tags. Daher ist main das einzige verfügbare bewegliche Ziel und wird mehrmals pro Woche geändert. Notieren Sie den getesteten SHA, stellen Sie genau diesen bereit und prüfen Sie den Diff, bevor Sie aktualisieren. git log --oneline <old-sha>..main ist die maßgebliche Prüfung. Die .env.example-Dateien der einzelnen Anwendungen sind die erste Anlaufstelle für neu erforderliche Variablen nach einer Aktualisierung.