superloglabs/superlog : de l'OTLP ingéré aux incidents regroupés, avec un runner d'agent à brancher

Le problème visé : trier le bruit avant de chercher la cause

Une stack instrumentée avec OpenTelemetry produit des traces, des logs et des métriques en continu. Le volume n'est pas le seul obstacle. Le même défaut d'un service amont se manifeste dans plusieurs services en aval, avec des messages différents et des horodatages décalés. Superlog se place exactement à cet endroit : il ingère les trois signaux, les regroupe en incidents, et expose le résultat dans un espace de travail local. Le README résume la promesse en une phrase : ingérer, regrouper les signaux bruyants, et surveiller l'infrastructure pendant la nuit. Le public visé est donc une équipe d'ingénieurs qui exploite déjà des collecteurs OTLP et qui veut un endroit où les symptômes sont rassemblés avant l'investigation. Le sous-titre du dépôt parle d'agents IA qui réparent le logiciel. C'est la direction du projet, pas ce que fait l'édition communautaire livrée ici : celle-ci s'arrête au regroupement et à un runner d'agent par défaut qui écrit un résumé local. Cette distinction change complètement la décision d'adoption, et le README la rend explicite en listant le contenu de l'édition gratuite.

Quatre processus, deux bases : le trajet d'un signal

Le dépôt est un monorepo pnpm dont la disposition est documentée dans le README. apps/proxy reçoit l'OTLP. apps/api sert l'interface HTTP. apps/web est le front Vite et React. apps/worker héberge les traitements d'arrière-plan et l'orchestration des agents. Côté stockage, packages/db contient le schéma Drizzle et les migrations vers Postgres, tandis que les requêtes sur la télémétrie s'appuient sur ClickHouse. Le partage est cohérent : Postgres garde l'état de l'application et des incidents, ClickHouse absorbe les volumes de télémétrie. Un paquet distinct, packages/fingerprint, fournit les fonctions d'empreinte des signaux. C'est lui qui décide que deux erreurs distinctes appartiennent au même incident, et le README ne détaille pas son algorithme. Toute la qualité du regroupement repose pourtant sur ce paquet. Les interfaces de runner d'agent sont également dans le worker, ce qui signifie que le remplacement du runner par défaut est un point d'extension prévu, pas un détournement. En revanche, le README ne décrit ni le format d'échange entre le proxy et le worker, ni la latence attendue entre l'arrivée d'un span et son rattachement à un incident. Ce sont deux zones à inspecter dans le code avant de dimensionner quoi que ce soit.

Mise en route : trois commandes et un port par service

Les prérequis annoncés sont Node.js 20 ou plus, pnpm 9 ou plus, et Docker. L'installation des dépendances se fait avec pnpm install. Le démarrage de la pile locale enchaîne trois commandes : docker compose up -d, puis pnpm --filter @superlog/db db:migrate, puis pnpm dev. La migration est une étape séparée et non automatique, ce qui est un choix raisonnable en développement mais implique de la rejouer à chaque changement de schéma. Les services exposés par défaut sont l'interface web sur http://localhost:5173, l'API sur http://localhost:4100 et l'entrée OTLP sur http://localhost:4101. Pour brancher une application existante, il suffit donc de pointer son exportateur OTLP vers le port 4101. Le README propose aussi une seconde voie d'installation, via un agent de codage : exécuter npx skills add superloglabs/skills --all puis demander à l'agent d'installer Superlog dans le projet. Cette approche délègue la configuration à un agent, ce qui va vite mais rend la reproductibilité dépendante de ce que l'agent décide d'écrire. Pour un environnement d'équipe, la séquence documentée en trois commandes reste la référence vérifiable. La vérification de types passe par pnpm typecheck.

Le runner community : un point d'extension, pas une réparation

C'est ici que l'écart entre le titre du dépôt et le contenu du dépôt est le plus net. Le README liste, parmi les composants de l'édition communautaire, des interfaces de runner d'agent pour des moteurs d'investigation enfichables, et un runner par défaut nommé community qui enregistre un résumé d'incident local. Autrement dit, la boucle d'investigation automatique est présente sous forme de contrat d'interface, et l'implémentation fournie se limite à de l'écriture. Rien dans le matériel ne décrit un mécanisme de correction automatique du code, de redéploiement ou de retour arrière. Une équipe qui lit la description et attend une auto-réparation se trompera de produit. Une équipe qui veut un socle d'ingestion et de regroupement, avec un endroit propre où brancher son propre agent, trouve ici exactement ce qu'elle cherche. La nuance est importante pour l'évaluation : le travail à fournir n'est pas nul, il consiste à écrire un runner conforme aux interfaces exposées dans apps/worker, puis à le faire charger par le worker. Le README ne documente pas cette procédure, il faut donc la déduire du code. C'est la principale dette de documentation du projet.

Ce que le dépôt ne dit pas

Plusieurs questions restent sans réponse dans le matériel fourni, et il vaut mieux les traiter comme des inconnues que comme des acquis. La rétention des données dans ClickHouse n'est pas précisée. Les valeurs par défaut de docker compose ne sont pas listées. Aucune variable d'environnement n'est nommée, ni pour l'authentification de l'API, ni pour la connexion aux bases, ni pour le choix du runner. Aucune information n'est donnée sur la montée en charge du proxy OTLP, ni sur ce qui se passe lorsque le worker tombe : les incidents en cours de regroupement sont-ils perdus ou rejoués. Le README mentionne une édition hébergée avec un niveau gratuit, un plan à l'usage et des forfaits de crédits mensuels, mais ne décrit pas les écarts fonctionnels entre les deux éditions au-delà de la liste des composants communautaires. Enfin, le dépôt ne contient aucune release publiée au moment de la consultation, ce qui signifie qu'il n'existe pas de version étiquetée à épingler. Pour un déploiement, cela implique de suivre la branche main ou de figer un commit précis, et d'assumer le coût de mise à jour correspondant. La licence Apache-2.0 autorise l'usage commercial et la modification, avec les obligations habituelles de conservation des mentions et d'indication des changements. Ce paragraphe n'est pas un avis juridique.

Face à un collecteur plus un tableau de bord

L'alternative la plus directe n'est pas un autre produit d'observabilité, c'est l'assemblage d'un collecteur OpenTelemetry et d'un backend de stockage, avec des règles d'alerte écrites à la main. Dans cette approche, le regroupement n'existe pas comme concept de premier ordre : chaque règle évalue un signal isolé et déclenche une notification. Deux erreurs liées par une cause commune produisent deux alertes, et c'est à l'astreinte de faire le rapprochement. Superlog déplace ce travail en amont, dans un worker qui regroupe avant que l'humain regarde. La différence de coût est réelle dans les deux sens : l'assemblage classique se configure avec des fichiers de règles explicites et lisibles, tandis que le regroupement de Superlog dépend de packages/fingerprint dont la logique n'est pas documentée. Un faux regroupement, c'est-à-dire deux incidents distincts fusionnés, est plus difficile à diagnostiquer qu'une règle d'alerte mal écrite, parce qu'il n'y a pas de fichier à relire. À l'inverse, une équipe qui n'a pas envie d'écrire et de maintenir des dizaines de règles trouvera le modèle de Superlog plus économe. Le choix se joue donc sur la prévisibilité voulue : règles explicites d'un côté, empreinte algorithmique de l'autre.

Coût de maintenance et suite à donner

Le coût de maintenance se lit dans la pile elle-même. Il y a quatre applications Node à construire et à déployer, deux bases de données à sauvegarder et à mettre à jour, et un schéma Drizzle dont les migrations se lancent avec pnpm --filter @superlog/db db:migrate. Ce n'est pas un agent unique à poser sur une machine. La dépendance à ClickHouse pour les requêtes de télémétrie est le poste le plus lourd, en exploitation comme en sauvegarde. L'absence de release étiquetée ajoute une contrainte de suivi : sans version publiée, chaque mise à jour se fait au commit, et il n'existe pas de notes de version pour annoncer les ruptures. La licence Apache-2.0 ne pose pas de barrière à un usage interne ou à une modification, mais elle n'offre aucune garantie de support. Le premier pas concret, avant tout déploiement, consiste à ouvrir packages/fingerprint et apps/worker dans un clone, et à vérifier deux choses : comment une empreinte est calculée à partir d'un span, et quel contrat exact doit respecter un runner d'investigation. Si ces deux lectures sont concluantes pour votre cas, la pile se lance en trois commandes et vous saurez à quoi vous vous engagez.

Conclusion éditoriale

Superlog convient aux équipes qui veulent déjà parler OTLP et préfèrent héberger elles-mêmes l'ingestion et le regroupement d'incidents, plutôt que de payer un backend SaaS. Il ne convient pas à qui attend une remédiation automatique sans écrire de runner : le runner par défaut se contente d'enregistrer un résumé local. Avant d'adopter, vérifiez deux choses dans votre clone : le contenu réel de packages/fingerprint, qui détermine la qualité du regroupement, et la façon dont apps/worker charge un runner d'investigation autre que community.

Sources officielles

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. superloglabs/superlog on GitHub