Oxynote vereint Live-Metriken und Dokumentation in einem selbst gehosteten Wiki

Am 13. Oktober 2026 haben die Entwickler der ttlcache-Bibliothek Oxynote veröffentlicht, ein Open-Source-technisches Wiki, das die Lücke zwischen Systemüberwachung und Dokumentation schließen soll. Diese selbst gehostete Plattform ermöglicht es Engineering-Teams, Live-Metrik-Charts direkt neben ihren erklärenden Texten einzubetten, um sicherzustellen, dass der operative Kontext mit den visuellen Daten synchronisiert bleibt.

Was passiert ist

Oxynote adressiert ein häufiges Fragmentierungsproblem in modernen DevOps-Workflows, bei dem Dashboards und Dokumentation in separaten Silos leben. Traditionell bieten Tools wie Grafana nur begrenzten Platz für Panel-Beschreibungen, während externe Wikis wie Notion nur statische oder eingeschränkte Ansichten dieser Dashboards einbetten können. Diese Trennung führt oft zu Drift, bei dem die Erklärung im Wiki nicht mehr mit dem aktuellen Zustand oder der Konfiguration des referenzierten Charts übereinstimmt. Oxynote löst dieses Problem, indem es Abfragen für Prometheus, PostgreSQL, MySQL und MariaDB direkt innerhalb der Dokumentationsseite ausführt und so die Daten und ihre narrative Einbettung an einem einzigen, versionskontrollierten Ort hält.

Das Projekt entstand aus den frustrierenden Erfahrungen seiner Gründer, die feststellten, dass sie sich bei kritischen Systeminformationen primär auf private Slack-Chats als Quelle der Wahrheit verließen. Als Dienste, die Finanzmarktdaten verarbeiten, unter Memory-Leaks und Ausfällen litten, versagten bestehende Dashboards darin, die Ursachen hervorzuheben, was Ingenieure zwang, Health Checks und Backfill-Skripte manuell auszuführen. Das Fehlen integrierter Dokumentation führte dazu, dass neue Teammitglieder während On-Call-Schichten Schwierigkeiten hatten, komplexe Monitoring-Oberflächen wie Datadog ohne klare, zugängliche Erklärungen zu interpretieren, die direkt mit den relevanten Metriken verknüpft waren.

Um diesen Wissensverlust zu verhindern, führt Oxynote einen Review-Workflow ähnlich Code-Pull-Requests ein. Änderungen an der Dokumentation, einschließlich Updates von Metrik-Abfragen oder Schwellenwert-Erklärungen, durchlaufen eine Entwurfsphase mit visuellen Diffs. Dies stellt sicher, dass sowohl die technische Konfiguration als auch ihr menschenlesbarer Kontext gemeinsam geprüft und genehmigt werden, bevor sie in den Hauptzweig gemergt werden, was das Risiko veralteter oder irreführender operativer Leitfäden reduziert.

Wichtige Details

• Live-Metrik-Integration: Unterstützt Zeitreihen, Balkendiagramme und Gauge-Anzeigen unter Verwendung von Abfragen aus Prometheus, PostgreSQL, MySQL und MariaDB.
• Vereinheitlichter Review-Prozess: Änderungen an Seiten durchlaufen einen Ablauf aus Entwurf, Diff und Genehmigung, der Metrik-Blöcke und Text als eine Einheit behandelt.
• Selbst gehostete Architektur: Läuft als einzelner Container via Docker, wobei Daten in einem Volume persistiert werden; keine externen gehosteten Dienste erforderlich.
• Kollaboratives Editieren: Bietet Echtzeit-Präsenzindikatoren, Block-Kommentare und Erwähnungen, die Benutzer per E-Mail benachrichtigen.
• KI-Unterstützung: Enthält einen eingebauten Assistenten namens Rubber Duck, der Seiten bearbeiten und Abfragen ausführen kann, indem er Modelle von Anthropic, OpenAI, Google oder lokale Ollama-Instanzen nutzt.
• Freshness Hooks: Seiten können Abhängigkeiten von GitHub-Dateien, Container-Images oder Daten tracken und lösen Erinnerungen aus, wenn sich zugrunde liegende Systeme ändern.

Hintergrund

Für viele Engineering-Teams werden Observability und Dokumentation von unterschiedlichen Tools verwaltet, die nicht effektiv miteinander kommunizieren. Dashboards bieten Echtzeit-Einblicke in die Systemgesundheit, fehlen aber den Raum für detaillierte prozedurale Kontexte. Umgekehrt bieten Wikis reichhaltige Textbearbeitung und historischen Kontext, können aber nativ keine Live-, abfragegesteuerten Daten anzeigen, ohne komplexe Einbettungen, die oft brechen oder separate Authentifizierung erfordern. Diese Diskonnektion zwingt Ingenieure dazu, mentale Karten darüber zu führen, welches Dashboard welcher Dokumentationsseite entspricht, was zu Fehlern während der Incident-Reaktion führt.

Oxynote versucht, diese Ebenen zu vereinheitlichen, indem es Dokumentation als dynamische Schnittstelle statt als statisches Protokoll behandelt. Durch die direkte Einbettung der Abfragelogik in die Seite wird sichergestellt, dass die visuelle Darstellung der Systemgesundheit immer an ihre Erklärung gebunden ist. Dieser Ansatz spiegelt das Konzept "Docs as Code" wider, bei dem Dokumentationsänderungen mit derselben Strenge versioniert und überprüft werden wie Softwareänderungen, erweitert dies jedoch um die Datenschicht der Visualisierung selbst.

Warum es wichtig ist

Für Teams, die ihre eigene Software betreiben, hängt die Geschwindigkeit der Incident-Lösung oft davon ab, wie schnell ein Ingenieur den aktuellen Zustand eines Systems verstehen kann. Wenn Metriken und Erklärungen getrennt sind, verschwenden On-Call-Ingenieure wertvolle Zeit damit, Tabs zu vergleichen und zu überprüfen, ob die gelesene Dokumentation noch auf die Live-Umgebung zutrifft. Oxynote reduziert diese kognitive Last, indem es den Graphen, die Erklärung und die relevanten Befehle auf einer einzigen Seite präsentiert, was es sowohl Menschen als auch KI-Agenten erleichtert, Probleme genau zu diagnostizieren.

Darüber hinaus hilft der Review-Mechanismus des Tools dabei, qualitativ hochwertiges operatives Wissen zu erhalten. In schnelllebigen Umgebungen ändern sich Dashboards häufig, wenn neue Labels hinzugefügt oder Schwellenwerte angepasst werden. Ohne einen vereinheitlichten Review-Prozess wird die Dokumentation schnell obsolet, was zu Verwirrung und potenziellen Fehlkonfigurationen führt. Durch die Erzwingung eines Entwurfs- und Genehmigungsworkflows für sowohl Text als auch Metriken stellt Oxynote sicher, dass das gemeinsame Verständnis des Teams für das System im Gleichschritt mit dem System selbst weiterentwickelt wird.

Was Sie tun können

• Stellen Sie Oxynote über den bereitgestellten Docker-Befehl bereit, um die Integration mit Ihren bestehenden Prometheus- oder SQL-Datenbanken zu testen.
• Identifizieren Sie kritische Dashboards in Ihrem aktuellen Setup, denen klare Dokumentation fehlt, und migrieren Sie sie zu Oxynote-Seiten mit eingebetteten Abfragen.
• Richten Sie eine Review-Richtlinie für operative Dokumentation ein, die Entwürfe und Genehmigungen für jede Änderung an Metrik-Schwellenwerten oder Erklärungen erfordert.
• Nutzen Sie die Freshness Hooks, um Dokumentationsseiten mit spezifischen Container-Images oder GitHub-Repositories zu verknüpfen, um Warnungen bei Aktualisierungen der Abhängigkeiten sicherzustellen.
• Konfigurieren Sie den Rubber-Duck-Assistenten mit einem lokalen Modell über Ollama, falls Datenschutzbedenken die Nutzung externer KI-Anbieter verhindern.