Trench : une image Docker pour brancher Kafka sur ClickHouse

Le problème : collecter des événements sans dépendre d'un SaaS

Une équipe produit veut savoir combien d'utilisateurs se connectent un compte, depuis quel pays, et à quelle fréquence. Les solutions hébergées répondent à cette question, mais elles imposent leurs tarifs à l'événement et gardent les données brutes chez le fournisseur. Trench prend le problème par l'autre bout : il fournit le tuyau de collecte et le stockage, et laisse l'équipe construire ce qu'elle veut au-dessus. Le README le formule ainsi : le projet a été construit pour « scale up the real-time event tracking pipeline » chez Frigade, ce qui indique une origine en production interne plutôt qu'un projet de démonstration. Le public visé est donc précis : des développeurs qui savent administrer un conteneur et une base de données, et qui veulent une API d'ingestion compatible avec l'écosystème Segment. Le dépôt est en TypeScript, sous licence MIT, et le README cite explicitement des cas d'usage comme les tableaux de bord produit, les RAG pour LLM ou les plateformes d'observabilité.

Kafka devant, ClickHouse derrière

L'architecture tient en deux briques. Les événements arrivent par HTTP sur une API compatible Segment, avec les trois appels Track, Group et Identify. Ils sont poussés dans Kafka, puis un consommateur les écrit dans ClickHouse, qui sert les requêtes. La documentation ne détaille pas le format des topics ni la stratégie de partitionnement, mais le trajet est visible dans les endpoints : POST /events pour l'ingestion, GET /events pour la lecture, POST /queries pour le SQL brut. Kafka joue ici le rôle de tampon : il absorbe les pics d'écriture pendant que ClickHouse ingère par lots, ce qui correspond au modèle habituel de ClickHouse, plus efficace sur de gros inserts que sur des écritures unitaires. Le README annonce « thousands of events per second on a single node » et des recommandations de 4 Go de RAM et 4 cœurs pour un environnement de production. Ces chiffres viennent du projet, pas d'une mesure indépendante, et ils dépendent évidemment de la forme des événements et du matériel.

Démarrer en local avec Docker Compose

Le seul prérequis annoncé est Docker et Docker Compose. Le README donne la séquence exacte : cloner le dépôt, se placer dans apps/trench, copier .env.example vers .env, puis lancer docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes. Cette commande démarre ClickHouse et Kafka en local et expose le serveur sur http://localhost:4000, qui doit répondre « Trench server is running ». Les clés d'API publiques et privées se trouvent dans le fichier .env et sont modifiables. L'envoi d'un événement se fait par un POST sur /events avec un en-tête Authorization: Bearer, un corps JSON contenant un tableau events, chaque entrée portant userId, type, event et properties. La lecture utilise GET /events?event=ConnectedAccount avec la clé privée, et renvoie un objet avec results, limit, offset et total. Le README indique une limite par défaut de 1000. Pour l'analyse, POST /queries accepte un tableau de chaînes SQL exécutées sur ClickHouse, par exemple un SELECT COUNT(*) FROM events WHERE userId = '...'. C'est le point le plus intéressant du projet : la table events est exposée telle quelle, sans couche de modélisation imposée.

Kafka authentifié, et ce qui n'est pas documenté

Le README consacre une section à l'authentification Kafka, avec des variables d'environnement toutes optionnelles : KAFKA_SSL_ENABLED, KAFKA_SSL_REJECT_UNAUTHORIZED, KAFKA_SSL_CA, KAFKA_SSL_CERT, KAFKA_SSL_KEY pour TLS et le mTLS, puis KAFKA_SASL_MECHANISM avec les valeurs plain, scram-sha-256 ou scram-sha-512, accompagnées de KAFKA_SASL_USERNAME et KAFKA_SASL_PASSWORD. Les certificats se fournissent en contenu PEM directement dans la variable. Ce niveau de détail suggère que le déploiement a été testé contre des clusters Kafka gérés, ce qui est cohérent avec une origine en production. En revanche, la documentation fournie s'arrête là. Rien n'indique comment les données sont effacées pour répondre à une demande RGPD, alors que le README revendique la conformité et le contrôle utilisateur sur l'accès, la rectification et la suppression. Rien n'indique non plus de politique de rétention, de gestion des migrations de schéma ClickHouse, ni de mécanisme de reprise après un arrêt prolongé du consommateur. Ces silences ne sont pas nécessairement des manques du logiciel, mais ils ne sont pas vérifiables à partir du matériel disponible.

Les limites structurelles du modèle

Trench n'est pas un entrepôt analytique. Il stocke des événements bruts et laisse l'utilisateur écrire son SQL. Toute la modélisation, les sessions, les cohortes, les entonnoirs, reste à construire. Une équipe qui attend des rapports prêts à l'emploi sera déçue. Le projet suppose aussi une certaine aisance avec Kafka et ClickHouse : ces deux systèmes ont leurs propres modes de panne, et Trench ne les masque pas. Le README recommande lui-même une taille de machine, ce qui revient à dire que le dimensionnement fait partie du travail d'exploitation. Autre point, la conformité revendiquée repose sur l'absence de cookies côté client, mais l'API accepte un userId arbitraire. Si cet identifiant est un email ou un identifiant interne stable, la conformité devient une affaire de choix d'implémentation, pas une propriété du logiciel. Enfin, l'API est compatible Segment, ce qui facilite la migration depuis cet écosystème, mais rien n'indique dans le matériel fourni quelles fonctionnalités de Segment sont absentes.

Face à Plausible ou Matomo

Les topics du dépôt mentionnent matomo, plausible-analytics et posthog, ce qui situe le voisinage. La différence d'approche est nette. Plausible et Matomo produisent des rapports web prêts à l'emploi : pages vues, sources de trafic, taux de rebond, avec une interface fournie. Trench ne fournit pas d'interface de rapport. Il fournit une API d'ingestion et un accès SQL à une table d'événements. Le README cite d'ailleurs une démonstration où l'on construit « a basic version of Google Analytics using Trench and Grafana », ce qui confirme le partage des rôles : Trench collecte et stocke, un outil de visualisation externe affiche. Le choix se fait donc sur ce critère. Si l'objectif est de mesurer l'audience d'un site vitrine, Plausible ou Matomo seront plus rapides à mettre en service. Si l'objectif est de bâtir un produit analytique sur des événements applicatifs, avec des requêtes arbitraires et des sorties personnalisées, l'accès SQL direct de Trench est l'argument principal. PostHog se situe entre les deux, avec une couverture fonctionnelle plus large que celle décrite ici.

Coût d'exploitation et licence

Le coût réel d'un déploiement Trench est celui de Kafka et de ClickHouse. Ces deux composants consomment de la mémoire et du disque, et leur exploitation demande du temps : sauvegardes, mises à jour, surveillance de la consommation disque. Le README recommande 4 Go de RAM et 4 cœurs, ce qui correspond à un point de départ, pas à une garantie de tenue dans la durée. La licence MIT du dépôt est permissive : usage commercial, modification et redistribution sont autorisés, avec conservation de la mention de copyright. Cette licence couvre le code de Trench, pas Kafka ni ClickHouse, qui ont leurs propres licences et qu'il faut vérifier séparément. Le matériel fourni ne dit rien du rythme de publication, et la dernière version listée, trench-js@0.0.17, date de décembre 2024, tandis que le dernier push sur la branche main est daté d'avril 2026. Ces deux dates ne suffisent pas à conclure quoi que ce soit sur l'activité du projet, mais elles méritent d'être regardées de près avant de s'engager.

Conclusion éditoriale

Trench convient aux équipes qui ont déjà Docker en production et qui acceptent d'exploiter elles-mêmes Kafka et ClickHouse pour garder la main sur leurs données d'événements. Il ne convient pas à qui cherche un produit clé en main sans compétence en exploitation de bases de données, ni à qui veut un entrepôt analytique généraliste. Avant d'adopter, vérifier deux points dans le dépôt : la présence d'un mécanisme d'authentification sur l'API en dehors des clés publiques et privées, et la façon dont les migrations de schéma ClickHouse sont appliquées lors d'une mise à jour d'image.

Sources officielles

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