Trench: selbstgehostete Event-Pipeline mit Kafka und ClickHouse in einem Docker-Image

Welches Problem Trench löst und für wen es gedacht ist

Die meisten Analytics-Produkte setzen voraus, dass die Ereignisse in einer fremden Cloud landen. Trench dreht das um. Das Projekt beschreibt sich selbst als Event-Tracking-System auf Basis von Apache Kafka und ClickHouse, das laut README große Ereignisvolumen verarbeiten und Echtzeit-Analysen liefern soll. Der Anspruch ist nicht, ein fertiges Dashboard zu sein, sondern die Infrastruktur darunter: Aufnahme, Zwischenspeicherung, Speicherung und Abfrage. Wer darauf aufbauen will, baut die Oberfläche selbst oder verbindet ein BI-Werkzeug. Das README verweist auf eine Demo, in der eine einfache Version von Google Analytics mit Trench und Grafana nachgebaut wird. Das ist die ehrlichste Beschreibung des Zielbilds: Trench liefert die Daten, die Visualisierung kommt von außen. Die Zielgruppe sind entsprechend nicht Marketing-Teams, sondern Plattform- und Backend-Teams, die Tracking als Infrastruktur betreiben und die Datenhoheit behalten wollen. Das README nennt GDPR- und PECR-Konformität sowie den Verzicht auf Cookies als Eigenschaften. Solche Aussagen sind Einordnungen des Projekts, keine unabhängige Prüfung, und sollten vor einem Einsatz gegen die eigenen rechtlichen Anforderungen gehalten werden.

Kafka als Puffer, ClickHouse als Ablage, Node.js als Vermittler

Aus dem Repository und dem README lässt sich eine dreistufige Kette ablesen. Der Node.js-Server nimmt HTTP-Ereignisse entgegen. Er schreibt sie in einen Kafka-Topic, der als Puffer dient und Lastspitzen vom Speicher entkoppelt. Ein Konsument liest aus Kafka und schreibt die Ereignisse nach ClickHouse, wo sie für Abfragen bereitstehen. Die Antwort auf eine Abfrage enthält laut README neben den eigentlichen Ergebnissen die Felder limit, offset und total, was auf eine paginierte Abfrageschicht über ClickHouse hindeutet. Ein Feld parsedAt im zurückgegebenen Ereignis trennt den Zeitpunkt des Ereignisses vom Zeitpunkt der Verarbeitung. Diese Trennung ist der sichtbare Beleg für die asynchrone Verarbeitung: Zwischen dem POST und dem Erscheinen des Datensatzes in einer Abfrage liegt die Pipeline. Wer ein sofort konsistentes Lesen nach dem Schreiben erwartet, wird hier enttäuscht. Die Architektur erkauft Durchsatz mit Verzögerung. Das ist eine bewusste Entscheidung, die zu Analyse-Workloads passt und zu transaktionalen Anwendungen nicht.

Quickstart: Klonen, konfigurieren, hochfahren

Der Einstieg ist bewusst kurz gehalten. Voraussetzung sind Docker und Docker Compose. Das README empfiehlt mindestens 4 GB RAM und 4 CPU-Kerne für eine Produktionsumgebung. Die Befehlsfolge aus der Dokumentation lautet: git clone https://github.com/frigadehq/trench.git, danach cd trench/apps/trench, dann cp .env.example .env, und schließlich docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes. Der Server läuft anschließend auf http://localhost:4000 und meldet Trench server is running. Die Kombination beider Compose-Dateien ist wichtig: docker-compose.dev.yml überschreibt die Basisdatei für die lokale Entwicklung. Für einen Produktivbetrieb ist diese Überlagerung vermutlich nicht die richtige Wahl, und das README sagt dazu nichts Ausdrückliches. Wer Trench ernsthaft betreiben will, muss die Basisdatei selbst lesen und anpassen. Die API-Schlüssel liegen in der .env-Datei. Das README zeigt ein Beispiel mit dem öffentlichen Schlüssel public-d613be4e-di03-4b02-9058-70aa4j04ff28 und einem privaten Schlüssel mit dem Präfix private-. Diese Werte sind Platzhalter aus der Vorlage und müssen vor jedem Deployment ersetzt werden. Der öffentliche Schlüssel ist für das Senden von Ereignissen gedacht, der private für Abfragen. Diese Trennung ist sinnvoll, weil sie das Schreiben vom Lesen entkoppelt, aber sie funktioniert nur, wenn der private Schlüssel tatsächlich nur serverseitig landet.

Ereignisse senden, abfragen und rohes SQL ausführen

Das Ereignisformat folgt der Segment-API. Das README nennt die Aufrufe Track, Group und Identify. Ein Beispiel aus der Dokumentation sendet per POST an http://localhost:4000/events einen Body mit einem events-Array, in dem ein Objekt die Felder userId, type, event und properties trägt. Der Header Authorization enthält Bearer gefolgt vom öffentlichen Schlüssel. Für die Abfrage gibt es GET auf denselben Pfad mit dem Parameter event, etwa /events?event=ConnectedAccount, autorisiert mit dem privaten Schlüssel. Die Antwort enthält ein results-Array mit uuid, type, event, userId, properties, timestamp und parsedAt sowie limit 1000, offset 0 und total 1. Zusätzlich bietet Trench einen Endpunkt /queries, an den per POST ein JSON-Objekt mit einem queries-Array aus SQL-Strings geschickt wird. Das README zeigt als Beispiel SELECT COUNT(*) FROM events WHERE userId = '550e8400-e29b-41d4-a716-446655440000'. Hier liegt der eigentliche Reiz des Projekts: Wer SQL kann, muss keine proprietäre Abfragesprache lernen. Zugleich ist das der riskanteste Teil. Ein Endpunkt, der beliebiges SQL entgegennimmt, verlagert die Zugriffskontrolle vollständig auf die Schlüsselverwaltung. Das README beschreibt keine rollenbasierte Rechtevergabe und keine Einschränkung auf bestimmte Tabellen oder Spalten. Wer den privaten Schlüssel weitergibt, gibt damit faktisch Lesezugriff auf die gesamte Ereignistabelle.

Kafka-Authentifizierung über Umgebungsvariablen

Für den Anschluss an einen externen Kafka-Cluster dokumentiert das README eine Reihe optionaler Umgebungsvariablen. KAFKA_SSL_ENABLED schaltet TLS ein und ist standardmäßig false. KAFKA_SSL_REJECT_UNAUTHORIZED steuert die Zertifikatsprüfung und steht standardmäßig auf true; das README empfiehlt ausdrücklich, den Wert nur bei selbstsignierten Zertifikaten in der Entwicklung auf false zu setzen. Für eine eigene Zertifizierungsstelle gibt es KAFKA_SSL_CA, für gegenseitige TLS-Authentifizierung zusätzlich KAFKA_SSL_CERT und KAFKA_SSL_KEY. Alle drei erwarten den PEM-Inhalt direkt, nicht einen Dateipfad. Das ist ein praktisches Detail, das bei Konfigurationssystemen mit Dateimounts zu Umwegen führt. Für SASL nennt das README KAFKA_SASL_MECHANISM mit den Werten plain, scram-sha-256 und scram-sha-512 sowie KAFKA_SASL_USERNAME und KAFKA_SASL_PASSWORD, die beide gesetzt sein müssen, sobald ein Mechanismus gewählt wird. Der Umfang dieser Liste zeigt, dass Trench nicht nur mit dem mitgelieferten Kafka im Compose-Stack gedacht ist, sondern als Konsument einer bestehenden Infrastruktur. Genau dort liegt der Übergang vom lokalen Test zum echten Betrieb, und genau dort endet die Dokumentation im vorliegenden Material: Wie sich mehrere Instanzen auf einen gemeinsamen Cluster verhalten und wie Konsumentengruppen benannt sind, geht daraus nicht hervor.

Wo Trench an seine Grenzen stößt

Die README-Angabe, dass auf einem einzelnen Knoten tausende Ereignisse pro Sekunde verarbeitet werden können, ist eine Kapazitätsaussage ohne Messkontext. Sie sagt nichts über Ereignisgröße, Anzahl der Properties oder Abfragelast parallel zum Schreiben. Wer diese Zahl als Planungsgrundlage nimmt, plant auf einer Basis, die das Material nicht belegt. Die schwerer wiegende Einschränkung ist anderer Art: Trench liefert keine Benutzeroberfläche für die Analyse. Es gibt keinen Dashboard-Builder, keine Funnel-Ansicht, keine Kohortenanalyse. Das README verweist für die Visualisierung auf Grafana in der Demo. Wer Produktmanager ohne SQL-Kenntnisse bedienen will, braucht also ein zusätzliches Werkzeug und jemanden, der die Abfragen schreibt und pflegt. Ein weiterer Punkt betrifft die Datenhaltung. ClickHouse ist ein spaltenorientierter Speicher für analytische Abfragen. Das README beschreibt keine Aufbewahrungsfristen und kein Löschkonzept für einzelne Nutzer, obwohl es GDPR-Konformität und das Recht auf Berichtigung und Löschung nennt. Wie eine Löschanfrage technisch umgesetzt wird, bleibt offen. Wer personenbezogene Daten dauerhaft speichert, muss diese Frage vor dem Deployment klären, nicht danach.

PostHog als Gegenentwurf und der Unterschied im Ansatz

Der naheliegende Vergleich ist PostHog, das in den Topics des Repositories selbst auftaucht. Der Unterschied liegt nicht im Funktionsumfang, sondern im Zuschnitt. PostHog ist als vollständiges Produkt gedacht: Aufnahme, Speicherung, Oberfläche, Sitzungsaufzeichnung und Feature-Flags in einer Anwendung. Trench ist die untere Schicht davon, ohne die obere. Wer PostHog selbst hostet, betreibt eine größere Anwendung mit mehr Komponenten und bekommt dafür die Analyseoberfläche mitgeliefert. Wer Trench betreibt, hat weniger bewegliche Teile, muss aber jede Auswertung selbst bauen. Der zweite Unterschied ist die Schnittstelle. Trench spricht die Segment-API und akzeptiert damit Clients, die bereits für Segment geschrieben wurden. Das senkt die Migrationskosten auf der Sendeseite erheblich, weil der Client-Code unverändert bleibt. Auf der Leseseite gibt es keine vergleichbare Standardisierung: Die Abfrage erfolgt über SQL gegen ClickHouse, und damit ist man an das Schema gebunden, das Trench anlegt. Ein Wechsel zu einem anderen Backend bedeutet, alle Abfragen neu zu schreiben. Die Topics des Repositories nennen außerdem Matomo und Plausible, also Werkzeuge mit fertigen Oberflächen und einem anderen Datenmodell. Wer eines davon betreibt, tauscht Trench nicht gegen etwas Gleichartiges, sondern gegen eine andere Kategorie von Software.

Lizenz, Wartung und der Aufwand nach dem ersten Start

Trench steht unter der MIT-Lizenz. Das ist eine permissive Lizenz: Sie erlaubt kommerzielle Nutzung, Veränderung und Weitergabe, verlangt aber, dass der Lizenztext und der Urheberrechtshinweis erhalten bleiben. Wer den Code verändert und als eigenes Produkt ausliefert, muss diese Hinweise beibehalten. Das ist eine technische Einordnung, keine Rechtsberatung; für verbindliche Fragen ist eine juristische Prüfung nötig. Interessant ist der Hinweis im README, dass das Team Trench gebaut hat, um die eigene Echtzeit-Pipeline bei Frigade zu skalieren. Das erklärt den Zuschnitt: Das Projekt löst ein internes Problem und wird nun offen angeboten. Es erklärt auch, warum die Oberfläche fehlt, denn die entsteht bei Frigade vermutlich getrennt. Die Release-Liste zeigt die JavaScript-Pakete trench-js und analytics-plugin-trench mit Versionen aus dem Dezember 2024, während der letzte Push des Repositories im April 2026 liegt. Aus diesen Angaben lässt sich keine Aussage über die Häufigkeit künftiger Releases ableiten. Wer Trench produktiv einsetzt, übernimmt den Betrieb von Kafka und ClickHouse mit allen Upgrades, Schemaänderungen und Backup-Konzepten. Das ist der eigentliche Kostenblock, nicht das Image selbst.

Redaktionelles Fazit

Trench passt zu Teams, die Event-Daten auf eigener Infrastruktur halten müssen, die Segment-API bereits im Client sprechen und Rohabfragen in SQL akzeptieren. Wer eine fertige Oberfläche für Produktmanager braucht, sollte nicht damit anfangen, denn das Projekt liefert die Pipeline, nicht das Dashboard. Vor dem ersten Produktiv-Deployment sind drei Dinge zu prüfen: ob die im README genannten 4 GB RAM und 4 CPU-Kerne für das erwartete Volumen reichen, ob die private API key tatsächlich nur serverseitig verwendet wird, und ob die im Repository vorhandene docker-compose.dev.yml für den Produktivbetrieb durch eine eigene Konfiguration ersetzt wird, da sie ausdrücklich als Entwicklungsumgebung beschrieben ist.

Offizielle Quellen

1. FrigadeHQ/trench on GitHub
2. License: MIT
3. Project website
4. README
5. Releases