Oxynote fusionan métricas en vivo y documentación en un wiki autoalojado

El 13 de octubre de 2026, los desarrolladores detrás de la biblioteca ttlcache lanzaron Oxynote, un wiki técnico de código abierto diseñado para cerrar la brecha entre el monitoreo del sistema y la documentación. Esta plataforma autoalojada permite a los equipos de ingeniería incrustar gráficos de métricas en vivo directamente junto a su texto explicativo, asegurando que el contexto operativo permanezca sincronizado con los datos visuales.

Qué ocurrió

Oxynote aborda un problema común de fragmentación en los flujos de trabajo modernos de DevOps, donde los paneles de control y la documentación residen en silos separados. Tradicionalmente, herramientas como Grafana ofrecen espacio limitado para descripciones de paneles, mientras que wikis externos como Notion solo pueden incrustar vistas estáticas o restringidas de dichos paneles. Esta separación suele provocar desviaciones, donde la explicación en un wiki ya no coincide con el estado actual o la configuración del gráfico al que hace referencia. Oxynote resuelve esto ejecutando consultas para Prometheus, PostgreSQL, MySQL y MariaDB directamente dentro de la página de documentación, manteniendo los datos y su narrativa en una única ubicación bajo control de versiones.

El proyecto nació de las experiencias frustrantes de sus creadores, quienes se encontraban dependiendo de chats privados de Slack como fuente principal de verdad para información crítica del sistema. Cuando servicios que manejaban datos de mercados financieros sufrieron fugas de memoria y caídas, los paneles de control existentes no lograban destacar las causas raíz, obligando a los ingenieros a ejecutar manualmente comprobaciones de salud y scripts de relleno de datos. La falta de documentación integrada significaba que, durante los turnos de guardia, los nuevos miembros del equipo tenían dificultades para interpretar interfaces complejas de monitoreo como Datadog sin explicaciones claras y accesibles vinculadas directamente a las métricas relevantes.

Para evitar esta pérdida de conocimiento, Oxynote introduce un flujo de revisión similar a las solicitudes de extracción (pull requests) de código. Los cambios en la documentación, incluidas las actualizaciones de consultas de métricas o explicaciones de umbrales, pasan por una fase de borrador con diffs visuales. Esto garantiza que tanto la configuración técnica como su contexto legible por humanos sean revisados y aprobados juntos antes de fusionarse en la rama principal, reduciendo el riesgo de guías operativas obsoletas o engañosas.

Detalles clave

• Integración de Métricas en Vivo: Admite series temporales, gráficos de barras y medidores utilizando consultas de Prometheus, PostgreSQL, MySQL y MariaDB.
• Proceso de Revisión Unificado: Los cambios en las páginas siguen un flujo de borrador, diff y aprobación que trata los bloques de métricas y el texto como una unidad única.
• Arquitectura Autoalojada: Se ejecuta como un único contenedor mediante Docker, con datos persistidos en un volumen, sin requerir servicios alojados externos.
• Edición Colaborativa: Incluye indicadores de presencia en tiempo real, comentarios a nivel de bloque y menciones que notifican a los usuarios por correo electrónico.
• Asistencia con IA: Incorpora un asistente integrado llamado Rubber Duck que puede editar páginas y ejecutar consultas utilizando modelos de Anthropic, OpenAI, Google o instancias locales de Ollama.
• Ganchos de Actualización (Freshness Hooks): Las páginas pueden rastrear dependencias en archivos de GitHub, imágenes de contenedores o fechas, activando recordatorios cuando los sistemas subyacentes cambian.

Contexto

Para muchos equipos de ingeniería, la observabilidad y la documentación son gestionadas por herramientas distintas que no se comunican eficazmente. Los paneles de control ofrecen visibilidad en tiempo real sobre la salud del sistema pero carecen de espacio para el contexto procedimental detallado. Por el contrario, los wikis ofrecen edición rica de texto y contexto histórico, pero no pueden mostrar nativamente datos en vivo impulsados por consultas sin incrustaciones complejas que a menudo se rompen o requieren autenticación separada. Esta desconexión obliga a los ingenieros a mantener mapas mentales de qué panel corresponde a qué página de documentación, lo que lleva a errores durante la respuesta a incidentes.

Oxynote intenta unificar estas capas tratando la documentación como una interfaz dinámica en lugar de un registro estático. Al incrustar la lógica de consulta directamente en la página, asegura que la representación visual de la salud del sistema esté siempre ligada a su explicación. Este enfoque refleja el concepto de "docs as code" (documentación como código), donde los cambios en la documentación se versionan y revisan con el mismo rigor que los cambios de software, pero lo extiende para incluir la propia capa de visualización de datos.

Por qué importa

Para los equipos que ejecutan su propio software, la velocidad de resolución de incidentes a menudo depende de qué tan rápido un ingeniero pueda entender el estado actual de un sistema. Cuando las métricas y las explicaciones están separadas, los ingenieros de guardia pierden tiempo valioso cruzando pestañas y verificando si la documentación que están leyendo aún aplica al entorno en vivo. Oxynote reduce esta carga cognitiva presentando el gráfico, la explicación y los comandos relevantes en una sola página, facilitando que tanto humanos como agentes de IA diagnostiquen problemas con precisión.

Además, el mecanismo de revisión de la herramienta ayuda a mantener un conocimiento operativo de alta calidad. En entornos de rápida evolución, los paneles de control cambian frecuentemente a medida que se añaden nuevas etiquetas o se ajustan umbrales. Sin un proceso de revisión unificado, la documentación se vuelve obsoleta rápidamente, generando confusión y posibles errores de configuración. Al imponer un flujo de trabajo de borrador y aprobación tanto para el texto como para las métricas, Oxynote asegura que la comprensión compartida del equipo sobre el sistema evolucione al mismo ritmo que el propio sistema.

Qué puedes hacer

• Implementa Oxynote usando el comando Docker proporcionado para probar su integración con tus bases de datos Prometheus o SQL existentes.
• Identifica paneles críticos en tu configuración actual que carecen de documentación clara y migralos a páginas de Oxynote con consultas incrustadas.
• Establece una política de revisión para la documentación operativa, requiriendo borradores y aprobaciones para cualquier cambio en umbrales de métricas o explicaciones.
• Utiliza los ganchos de actualización (freshness hooks) para vincular páginas de documentación a imágenes de contenedores específicos o repositorios de GitHub, asegurando alertas cuando las dependencias se actualicen.
• Configura el asistente Rubber Duck con un modelo local vía Ollama si la privacidad de los datos impide el uso de proveedores de IA externos.
• Evalúa si la división actual entre tu wiki y las herramientas de monitoreo está causando retrasos en la incorporación de personal o fricción en la respuesta a incidentes.