Auto-héberger Superlog pour trier vos logs avec une IA

Ce que l’auto-hébergement de Superlog installe réellement

Pour auto-héberger Superlog, vous clonez le dépôt, démarrez Postgres, ClickHouse et un collecteur OpenTelemetry avec Docker Compose, exécutez une migration de base de données, puis lancez quatre services Node depuis les sources. Vos applications envoient des traces, des logs et des métriques OTLP (protocole OpenTelemetry) vers un port d’ingestion. Superlog les caractérise, regroupe les occurrences répétées dans un incident unique, puis un agent rédige une première analyse. L’installation prend un après-midi. L’empreinte et les limites réelles sont les points à lire avant de commencer.

Superlog est distribué sous licence Apache 2.0 et se trouve à l’adresse github.com/superloglabs/superlog. En août 2026, le projet compte environ 1.2k étoiles, environ 460 commits sur main, et aucune release taguée. Ce dernier point influence l’installation : git checkout v1.0.0 ne contient rien à extraire, vous devez donc épingler vous-même un commit ou exécuter la version de main présente le matin où vous l’avez cloné.

Ce à quoi Superlog répond, contrairement à Uptime Kuma et Langfuse

Les outils de monitoring auto-hébergés semblent interchangeables au premier abord. Ils ne le sont pas, et utiliser le mauvais outil vous fait mobiliser un serveur sans aucun bénéfice.

• Uptime Kuma sonde vos endpoints depuis l’extérieur et répond à une seule question : le service est-il disponible ?
• Zabbix surveille les hôtes et les services sur Ubuntu 24.04, en contrôlant le CPU, la mémoire, le disque et l’état des services par rapport aux seuils que vous avez définis.
• Langfuse trace les appels LLM, en enregistrant le prompt, le modèle, les tokens, la latence et le coût de chaque appel.
• Superlog exploite la télémétrie déjà produite par vos services courants et transforme les échecs répétés en incidents.

Superlog répond à une autre question : quelque chose est tombé en panne, qu’est-ce qui est en panne et pourquoi ? Il ne fait aucune hypothèse sur les appels LLM et ne vous sonde pas depuis l’extérieur. Il ingère les données OTLP produites par le code applicatif standard et place un agent à l’étape de triage, c’est-à-dire lors de la première analyse qu’effectuerait de toute façon la personne d’astreinte.

Pour le budget d’un VPS, la différence importante concerne le stockage. Uptime Kuma fonctionne sans problème avec 1 GB de RAM, car il stocke quelques milliers de résultats de contrôle. Superlog utilise un column store, car la télémétrie est écrite une seule fois, puis interrogée par plage temporelle sur des millions de lignes. C’est le rôle de ClickHouse, contrairement à Postgres. Postgres reste néanmoins dans la stack et stocke les petites données relationnelles : projets, utilisateurs, incidents et ingest keys.

Que démarre réellement docker compose up -d ?

Trois conteneurs, et aucun ne correspond à Superlog. Cela surprend les personnes qui s’attendent à une installation en une seule commande.

• postgres:16, publié sur le port hôte 5434
• clickhouse/clickhouse-server:26.1, sur le port 8123 pour HTTP et 9000 pour le protocole natif
• otel/opentelemetry-collector-contrib:0.150.1, sur le port 4317 pour gRPC et 4318 pour OTLP sur HTTP

Les applications Superlog s’exécutent sur l’hôte, depuis les sources, et sont lancées par pnpm dev. En août 2026, le dépôt ne contient pas de fichier compose destiné à la production. Une installation durable nécessite donc vos propres unités systemd autour du script start de chaque application, ou l’utilisation des Dockerfiles propres à chaque application, présents dans l’arborescence.

Gardez à l’esprit le chemin parcouru par une span, car chaque problème ci-dessous correspond à une rupture sur l’un de ses maillons. Votre application envoie l’OTLP au proxy d’ingestion Superlog. Le proxy authentifie la requête avec votre clé d’ingestion, lui attribue l’identifiant du projet, puis la transmet au collector. Le collector supprime tous les attributs superlog.* que le client a tenté de définir, ajoute superlog.project_id à partir de l’en-tête fourni par le proxy, regroupe les données par lots et les écrit dans ClickHouse. L’application web et l’API relisent ensuite la télémétrie depuis ClickHouse, et toutes les autres données depuis Postgres.

La suppression de ces attributs constitue un véritable contrôle de la colocation de projets, et non un simple élément décoratif. Sans elle, toute personne possédant une clé d’ingestion valide pourrait définir elle-même superlog.project_id et écrire dans les données d’un autre projet.

Quelle doit être la taille du VPS ?

Prévoyez 4 vCPU, 8 GB de RAM et 40 GB de SSD pour une installation single-node avec un faible volume d’ingestion. Il s’agit d’un seuil de planification, pas d’une mesure. Utilisez-le comme point de départ et vérifiez-le en fonction de votre propre trafic.

La mémoire est utilisée par quatre composants. ClickHouse est conçu pour des machines disposant de beaucoup de RAM, et ses valeurs par défaut partent de cette hypothèse. Postgres 16 reste modeste dans ce cas, car il stocke les métadonnées et non les données de télémétrie. Le collector est également peu gourmand. En revanche, les quatre processus Node ne le sont pas : un serveur de développement Vite et trois processus tsx watch utilisent chacun plusieurs centaines de mégaoctets. C’est pourquoi pnpm dev sur une machine de 2 GB devient difficile à gérer.

Le disque pose un problème moins visible. pnpm install dans ce monorepo installe le SDK AWS, un client ClickHouse, le SDK OpenTelemetry et une toolchain React avant même l’ingestion d’un seul span. ClickHouse augmente ensuite avec votre trafic. Mesurez les deux :

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"

À faible volume, avec quelques services qui envoient quelques centaines de spans par minute, la machine reste peu sollicitée et ClickHouse est inactif la plupart du temps. La charge problématique vient des pics : un déploiement défectueux peut produire des milliers d’erreurs identiques par minute. Le fingerprinting les regroupe en un seul incident pour le lecteur, mais ClickHouse écrit toujours chaque ligne sous-jacente.

C’est vous qui définissez la rétention. L’exporter ClickHouse du collector crée les tables, otel_traces, otel_logs et une table par type de métrique. Il applique une durée de vie uniquement si la configuration dans infra/collector/config.yaml en définit une. Rien n’expire automatiquement. Un mois de forte activité peut donc remplir entièrement le disque si vous ne l’anticipez pas.

Installer depuis un commit épinglé

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

git tag -l n’affichant rien est le résultat attendu en août 2026. Choisissez le commit que vous avez testé et restez dessus :

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Passez ensuite à la toolchain :

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

package.json déclare engines.node comme >=20.0.0 et packageManager comme pnpm@9.12.0. Si vous lancez l’installation avec une version plus ancienne de Node, pnpm s’arrête avec ERR_PNPM_UNSUPPORTED_ENGINE et indique la version requise. Le paquet nodejs de l’archive Ubuntu 24.04 est antérieur à la version 20. Installez donc Node 20 ou une version ultérieure depuis NodeSource ou nvm. Le dépôt fournit un .nvmrc ; nvm use sélectionne donc la version prévue si vous utilisez nvm.

pnpm install
docker compose up -d
docker compose ps

Attendez les health checks au lieu de considérer up -d comme une preuve que le service est prêt. Postgres et ClickHouse en déclarent tous les deux un dans le fichier Compose :

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

ClickHouse répond sur Ok. et pg_isready répond sur accepting connections. Une connexion refusée sur le port 8123 signifie que le conteneur est encore en cours de démarrage ou qu’il s’est arrêté. docker compose logs clickhouse indique lequel de ces cas s’applique, et docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled signale true lorsque le kernel l’a tué par manque de mémoire. Cela indique que la machine est sous-dimensionnée, et non que votre configuration est incorrecte.

Passez ensuite à la migration et aux applications :

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

Notez le port : 5434, et non 5432. Le fichier Compose publie Postgres sur le port 5434 afin d’éviter un conflit avec une instance Postgres déjà installée sur l’hôte. Les fichiers .env.example de l’application correspondent à ce choix, avec DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Si vous dirigez la migration vers le port 5432 sur une machine qui exécute déjà Postgres, vous obtenez soit une connexion refusée, soit, pire, une migration appliquée à la mauvaise base de données.

pnpm dev démarre les quatre processus listés dans le Procfile du dépôt : api, web, worker et proxy. Chaque processus envoie également sa sortie vers tmp/logs/ ; c’est donc dans tail -f tmp/logs/proxy.log que vous surveillez l’ingest. Le README indique que l’application web écoute sur http://localhost:5173, l’API sur http://localhost:4100 et la réception OTLP sur http://localhost:4101.

Vérifiez ce qui écoute réellement avant de configurer des clients :

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

Cela sera important par la suite. Le proxy lit son propre port dans la variable d’environnement PORT et utilise 4000 si PORT n’est pas définie. La stack de développement la définit pour vous. Une unité systemd que vous écrivez vous-même ne la définit pas. Un exporter configuré vers 4101 alors que le proxy écoute sur 4000 échoue donc avec une connexion refusée, sans fournir d’autre indication.

Envoyer une trace, produire une erreur, voir un incident

Créez un projet dans l’application web et copiez sa clé d’ingestion. Le point d’ingestion authentifie chaque requête avec cette clé. Les données de télémétrie envoyées sans clé n’atteignent donc jamais ClickHouse.

Configurez un SDK OpenTelemetry pour utiliser le point d’ingestion avec les variables d’environnement standard :

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'

Le point d’ingestion lit la clé dans l’en-tête x-api-key. Il accepte également authorization: bearer YOUR_INGEST_KEY si votre exporter est plus facile à configurer de cette manière. Il expose les trois chemins OTLP standard, /v1/traces, /v1/logs et /v1/metrics, ainsi que /health.

Un piège mérite d’être signalé. OTEL_EXPORTER_OTLP_ENDPOINT est une URL de base, et le SDK lui ajoute le chemin correspondant au signal. Les variables propres à chaque signal, comme OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, sont utilisées exactement telles quelles, sans ajout de chemin. Si vous définissez la variable propre au signal sur http://127.0.0.1:4101, chaque export est envoyé vers /. Il ne s’agit pas d’une route. Rien n’arrive donc au point d’ingestion, et le SDK journalise un échec d’export alors que votre application semble fonctionner normalement.

Pour un service Node, le chemin sans modification du code suffit à vérifier le pipeline :

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

Cassez maintenant quelque chose volontairement. N’importe quelle route qui lève une erreur convient :

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

Vérifiez les étapes dans l’ordre. La première interruption indique celle qui a échoué :

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

Un compteur otel_traces qui augmente alors que l’application web reste vide indique une erreur de projet. Vérifiez donc à quel projet appartient la clé d’ingestion. Un compteur stable avec de l’activité dans le journal du proxy indique un problème au niveau du collector ou de l’écriture dans ClickHouse. Consultez alors docker compose logs collector. L’absence totale d’activité dans le journal du proxy signifie que l’exporter n’a jamais atteint le point d’ingestion : port incorrect, chemin incorrect ou clé rejetée.

Dans l’application web, ces échecs répétés apparaissent comme un seul incident, et non comme une ligne par requête. Superlog calcule l’empreinte des signaux entrants et regroupe ceux qui correspondent. La différence est importante : la boîte de réception contient alors un seul incident au lieu de 4,000 erreurs identiques. L’agent rédige ensuite son analyse au-dessus de ce groupe.

L’étape d’analyse appelle un modèle. Le worker doit donc disposer d’un fournisseur de modèle configuré. Reprenez les noms de ces variables dans le fichier .env.example présent dans chaque répertoire d’application du commit que vous avez épinglé, et non dans une documentation externe. Ces noms évoluent avec main. La même règle s’applique aux intégrations GitHub et Sentry. Leurs propres documents de configuration se trouvent dans docs/github-app-setup.md et docs/sentry-app-setup.md, et la structure des payloads webhook est documentée dans docs/webhooks.md.

Protégez le point d’ingestion et gardez l’agent en lecture seule

Docker publie par défaut les ports des conteneurs sur 0.0.0.0. Ces ports publiés contournent ufw, car Docker écrit ses propres règles dans la chaîne DOCKER-USER, évaluée avant qu’ufw ne voie le paquet. Sur un VPS avec une IP publique, le fichier compose fourni expose ClickHouse HTTP sur 8123 et Postgres sur 5434, ce qui les rend accessibles depuis Internet. Les identifiants de ce fichier sont des valeurs par défaut de développement : l’utilisateur ClickHouse default avec un mot de passe vide, et Postgres avec postgres comme nom d’utilisateur et mot de passe.

Liez-les à l’interface loopback. Chaque port publié dans le fichier compose récupère son côté hôte depuis une variable d’environnement. Un fichier .env à la racine du dépôt suffit donc :

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

Vérifiez le résultat avant de lui faire confiance, puis recréez les conteneurs :

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

docker compose config affiche le fichier résolu. Vous pouvez donc lire 127.0.0.1:5434:5432 au lieu de deviner. ss doit ensuite afficher 127.0.0.1:5434 et ne jamais afficher 0.0.0.0:5434. N’essayez pas de corriger cela avec un fichier d’override compose qui redéclare ports. Compose concatène les listes de ports entre les fichiers au lieu de les remplacer. Vous vous retrouveriez donc avec les deux bindings, et le binding public resterait ouvert.

Le point d’ingestion nécessite les mêmes précautions. Votre clé d’ingestion transite dans un en-tête. Elle doit donc être protégée par TLS (transport layer security) : terminez TLS dans nginx ou Caddy en amont du proxy, ou gardez l’ingestion sur un réseau privé ou dans un tunnel WireGuard. L’application web sur 5173 est un serveur de développement Vite. Elle ne doit pas être exposée à Internet.

Passons à l’agent lui-même. Superlog présente l’agent comme un outil qui enquête et propose une correction. Le mot important est « propose ». Gardez-le en lecture seule sur la production jusqu’à l’avoir observé sur plusieurs incidents réels. Donnez à la GitHub App des scopes de lecture et autorisez-la à ouvrir des pull requests que vous examinerez. Un agent qui lit la télémétrie et écrit un patch est utile. Un agent capable de redémarrer vos services présente un niveau de risque différent. Cette capacité doit résulter d’une décision explicite, et non d’un comportement par défaut. Le coût nécessite la même attention, car chaque investigation correspond à un appel de modèle : prévoyez le budget consacré à l’agent sur un VPS avant de le diriger vers un système de production bruyant, et conservez un relevé de ce que l’agent a réellement fait afin que toute pull request surprenante dispose d’une piste d’audit.

Erreurs courantes et messages qui les désignent

• ERR_PNPM_UNSUPPORTED_ENGINE pendant pnpm install signifie que Node est antérieur à la version 20. node -v le confirme en une ligne.
• ECONNREFUSED 127.0.0.1:5434 pendant la migration signifie que la stack Compose n’est pas démarrée ou que DATABASE_URL indique le mauvais port.
• Un redémarrage en boucle de ClickHouse est généralement lié à la mémoire. Consultez docker compose logs clickhouse, puis vérifiez dans le conteneur que OOMKilled est bien true.
• Lorsqu’un exporter indique que tout a réussi alors que l’application web reste vide, cela signifie généralement que les données ont été envoyées directement au collector sur 4318. Cette méthode contourne l’ajout du projet par le proxy.
• Une connexion refusée sur 4101 dans une installation de production signifie que le proxy a utilisé PORT=4000 comme valeur de repli. Définissez explicitement PORT dans le fichier d’unité.
• Si docker compose ps affiche 0.0.0.0:8123, vos bindings loopback ne sont pas pris en compte. Exécutez docker compose config et consultez les ports résolus.

Flawless, HyperProbe et la place de Superlog

Cette catégorie est récente, et les outils se distinguent par ce que l’agent est autorisé à consulter. Flawless est un outil open source d’IA pour le SRE (site reliability engineering), destiné à Kubernetes. Il lit les données d’une stack Prometheus, Loki et Grafana existante au lieu de gérer lui-même le pipeline. HyperProbe suit l’approche inverse : en août 2026, c’est un produit hébergé et à source fermée. Il place des probes en lecture seule dans un processus en cours d’exécution afin de capturer l’état des variables, puis expose cet état à un assistant via MCP (model context protocol).

Superlog se situe entre les deux. Il gère le pipeline de bout en bout, de la réception OTLP au stockage dans ClickHouse. Il place l’agent à l’étape du triage, et non à celle de la correction. C’est précisément pourquoi son auto-hébergement relève d’une décision d’infrastructure, et non du simple déploiement d’un conteneur que l’on peut ensuite oublier. Une fois Superlog en production, vous exploitez un column store. Il demande la même maintenance que toute autre base de données dont vous avez la responsabilité.

FAQ

Combien de RAM faut-il à un Superlog auto-hébergé ?

Prévoyez 8 GB de RAM, 4 vCPU et 40 GB de stockage pour un nœud unique avec un faible volume d’ingestion. La stack comprend Postgres, ClickHouse, un collecteur OpenTelemetry et quatre processus Node. ClickHouse a également besoin d’une marge de ressources. Un VPS de 1 GB ou 2 GB ne suffit pas : pnpm install est déjà gourmand, et le kernel peut tuer ClickHouse avec l’out-of-memory killer sous charge. Mesurez vos propres valeurs avec docker stats --no-stream et free -m au lieu de vous fier à un chiffre publié, y compris celui-ci.

Vers quel port dois-je configurer mon exportateur OTLP ?

Le proxy d’ingestion Superlog, que le README configure sur http://localhost:4101. Il sert /v1/traces, /v1/logs et /v1/metrics, et s’authentifie avec la clé d’ingestion de votre projet, récupérée depuis l’en-tête x-api-key ou depuis un en-tête authorization: bearer. Le port 4318 correspond au collecteur OpenTelemetry situé en dessous. Y exporter directement contourne le proxy, qui est le composant chargé d’ajouter l’identifiant de votre projet aux données. Le proxy utilise le port 4000 si PORT n’est pas défini. Exécutez donc ss -lntp et vérifiez le port sur lequel il est en écoute avant de supposer qu’il s’agit du port 4101.

Superlog remplace-t-il Uptime Kuma ou Zabbix ?

Non. Uptime Kuma vérifie depuis l’extérieur de votre réseau si un endpoint répond. Zabbix surveille les métriques des hôtes et des services par rapport aux seuils que vous définissez. Superlog consomme les traces, les logs et les métriques émises par vos applications, puis regroupe les erreurs répétées en incidents. Conservez un probe de disponibilité externe en complément. Un probe exécuté ailleurs continue de signaler la panne lorsque le serveur qui héberge votre pipeline de télémétrie est lui-même à l’arrêt.

L’agent Superlog peut-il modifier mes systèmes de production ?

Uniquement avec les permissions que vous lui accordez. Sa sortie consiste en une investigation et en une modification proposée, qu’un humain examine. Au départ, limitez la GitHub App aux scopes de lecture et aux pull requests. Limitez également les credentials détenus par le worker à la lecture. Considérez l’accès en écriture à la production comme une décision distincte, à prendre délibérément. Un agent capable de redémarrer des services représente un engagement bien plus important qu’un agent qui lit la télémétrie et écrit un patch à soumettre à la review.

Dois-je figer un commit ou suivre main ?

Figez un commit. Le repository ne contient aucun release tag en août 2026. main est donc la seule cible mobile proposée, et elle reçoit plusieurs commits par semaine. Notez le SHA que vous avez testé et déployez celui-ci. Lisez le diff avant de passer à une version plus récente. git log --oneline <old-sha>..main correspond à la review. Les fichiers .env.example propres à chaque application sont le premier endroit à consulter pour repérer les nouvelles variables requises après une mise à jour.