Oxynote fusionne métriques en direct et documentation dans un wiki auto-hébergé

Le 13 octobre 2026, les développeurs derrière la bibliothèque ttlcache ont publié Oxynote, un wiki technique open source conçu pour combler le fossé entre la surveillance des systèmes et la documentation. Cette plateforme auto-hébergée permet aux équipes d'ingénierie d'intégrer des graphiques de métriques en temps réel directement à côté de leur texte explicatif, garantissant que le contexte opérationnel reste synchronisé avec les données visuelles.

Ce qui s'est passé

Oxynote répond à un problème courant de fragmentation dans les workflows DevOps modernes, où les tableaux de bord et la documentation vivent dans des silos séparés. Traditionnellement, des outils comme Grafana offrent peu d'espace pour les descriptions des panneaux, tandis que les wikis externes comme Notion ne peuvent intégrer que des vues statiques ou restreintes de ces tableaux de bord. Cette séparation conduit souvent à une dérive, où l'explication dans un wiki ne correspond plus à l'état actuel ou à la configuration du graphique qu'elle référence. Oxynote résout ce problème en exécutant des requêtes pour Prometheus, PostgreSQL, MySQL et MariaDB directement au sein de la page de documentation, maintenant ainsi les données et leur récit dans un emplacement unique et versionné.

Le projet est né des expériences frustrantes de ses créateurs, qui se sont retrouvés à dépendre de chats Slack privés comme principale source de vérité pour les informations critiques sur les systèmes. Lorsque des services traitant des données de marché financiers ont subi des fuites mémoire et des pannes, les tableaux de bord existants n'ont pas réussi à mettre en évidence les causes profondes, obligeant les ingénieurs à lancer manuellement des vérifications de santé et des scripts de remplissage. L'absence de documentation intégrée signifiait que, lors des astreintes, les nouveaux membres de l'équipe avaient du mal à interpréter des interfaces de surveillance complexes comme Datadog sans explications claires et accessibles liées directement aux métriques concernées.

Pour prévenir cette perte de connaissances, Oxynote introduit un flux de travail de revue similaire aux pull requests de code. Les modifications apportées à la documentation, y compris les mises à jour des requêtes de métriques ou des explications de seuils, passent par une phase de brouillon avec des diffs visuels. Cela garantit que la configuration technique et son contexte lisible par l'homme sont revus et approuvés ensemble avant la fusion dans la branche principale, réduisant le risque de guides opérationnels obsolètes ou trompeurs.

Détails clés

• Intégration de métriques en direct : Prend en charge les séries temporelles, les graphiques à barres et les jauges utilisant des requêtes depuis Prometheus, PostgreSQL, MySQL et MariaDB.
• Processus de revue unifié : Les modifications apportées aux pages suivent un flux de brouillon, de diff et d'approbation qui traite les blocs de métriques et le texte comme une seule unité.
• Architecture auto-hébergée : S'exécute comme un conteneur unique via Docker, avec des données persistées dans un volume, sans nécessiter de service hébergé externe.
• Édition collaborative : Propose des indicateurs de présence en temps réel, des commentaires au niveau des blocs et des mentions qui notifient les utilisateurs par e-mail.
• Assistance IA : Inclut un assistant intégré appelé Rubber Duck capable de modifier les pages et d'exécuter des requêtes en utilisant des modèles d'Anthropic, OpenAI, Google ou des instances locales Ollama.
• Hooks de fraîcheur : Les pages peuvent suivre les dépendances sur les fichiers GitHub, les images de conteneurs ou les dates, déclenchant des rappels lorsque les systèmes sous-jacents changent.

Contexte

Pour de nombreuses équipes d'ingénierie, l'observabilité et la documentation sont gérées par des outils distincts qui ne communiquent pas efficacement. Les tableaux de bord offrent une visibilité en temps réel sur la santé du système mais manquent d'espace pour un contexte procédural détaillé. Inversement, les wikis offrent une édition de texte riche et un contexte historique mais ne peuvent pas afficher nativement des données en direct pilotées par des requêtes sans intégrations complexes qui cassent souvent ou nécessitent une authentification séparée. Cette déconnexion force les ingénieurs à maintenir des cartes mentales indiquant quel tableau de bord correspond à quelle page de documentation, entraînant des erreurs lors de la réponse aux incidents.

Oxynote tente d'unifier ces couches en traitant la documentation comme une interface dynamique plutôt que comme un registre statique. En intégrant la logique de requête directement dans la page, il garantit que la représentation visuelle de la santé du système est toujours liée à son explication. Cette approche reflète le concept de « docs as code », où les modifications de documentation sont versionnées et revues avec la même rigueur que les modifications logicielles, mais l'étend pour inclure la couche de visualisation des données elle-même.

Pourquoi c'est important

Pour les équipes qui exploitent leur propre logiciel, la vitesse de résolution des incidents dépend souvent de la rapidité avec laquelle un ingénieur peut comprendre l'état actuel d'un système. Lorsque les métriques et les explications sont séparées, les ingénieurs d'astreinte perdent un temps précieux à croiser les onglets et à vérifier que la documentation qu'ils lisent s'applique toujours à l'environnement en production. Oxynote réduit cette charge cognitive en présentant le graphique, l'explication et les commandes pertinentes sur une seule page, facilitant le diagnostic précis des problèmes tant pour les humains que pour les agents IA.

De plus, le mécanisme de revue de l'outil aide à maintenir une connaissance opérationnelle de haute qualité. Dans des environnements rapides, les tableaux de bord changent fréquemment à mesure que de nouvelles étiquettes sont ajoutées ou que des seuils sont ajustés. Sans un processus de revue unifié, la documentation devient rapidement obsolète, entraînant confusion et risque de mauvaise configuration. En imposant un flux de travail de brouillon et d'approbation pour le texte et les métriques, Oxynote garantit que la compréhension partagée du système par l'équipe évolue en parallèle avec le système lui-même.

Ce que vous pouvez faire

• Déployez Oxynote en utilisant la commande Docker fournie pour tester son intégration avec vos bases de données Prometheus ou SQL existantes.
• Identifiez les tableaux de bord critiques dans votre configuration actuelle qui manquent de documentation claire et migrez-les vers des pages Oxynote avec des requêtes intégrées.
• Établissez une politique de revue pour la documentation opérationnelle, exigeant des brouillons et des approbations pour toute modification des seuils de métriques ou des explications.
• Utilisez les hooks de fraîcheur pour lier les pages de documentation à des images de conteneurs spécifiques ou à des dépôts GitHub, garantissant des alertes lorsque les dépendances sont mises à jour.
• Configurez l'assistant Rubber Duck avec un modèle local via Ollama si la confidentialité des données empêche l'utilisation de fournisseurs d'IA externes.
• Évaluez si la séparation actuelle entre votre wiki et vos outils de surveillance cause des retards d'intégration ou des frictions lors de la réponse aux incidents.