Oxynote: documentación técnica viva con métricas integradasArtículo · digest del 18 de octubre
Diagrama isométrico arquitectónico de la plataforma Oxynote: página de documentación técnica con un bloque integrado de gráficos de métricas en vivo y una rama de revisión.
Artículo3 secciones≈ 4 min

Oxynote: documentación técnica viva con métricas integradas

Piensa en cómo suele ser investigar una caída seria en tu proyecto. En una pestaña del navegador tienes Grafana abierto con el pico de errores 500 y el pool de conexiones al límite. En la otra, el runbook en Notion o en el Confluence de la empresa, escrito hace un año por un compañero que ya ni trabaja ahí.

Miras la gráfica y tratas de adivinar: ¿400 conexiones activas a la base de datos son un pico normal o ya un atasco crítico? En Grafana no hay dónde explicarlo más allá de una diminuta descripción en el panel. Y si intentas incrustar el dashboard en la wiki corporativa con un iframe, acabas peleándote con la autenticación y sin ningún control de versiones.

Los creadores de la popular librería ttlcache han decidido cerrar esa brecha de contexto lanzando el proyecto abierto Oxynote bajo licencia Apache 2.0. Lo llaman «documentación que respira» (breathing docs): una base de conocimiento donde las métricas en vivo y el texto de los procedimientos conviven en el mismo sitio.

Bloques de métricas en vivo dentro del texto

En lugar de capturas estáticas o marcos externos, Oxynote utiliza bloques nativos de Live Metrics. Dentro de un párrafo normal de documentación puedes insertar gráficas de series temporales, histogramas o indicadores circulares (gauges).

Cada bloque se conecta directamente a la fuente de datos: soporta consultas PromQL contra Prometheus y SQL directo sobre bases relacionales (PostgreSQL, MySQL, MariaDB). Justo debajo de la gráfica defines el criterio de normalidad: «Si la tasa de errores supera el 5 % durante más de 3 minutos seguidos, ejecuta estos pasos». El ingeniero ve las cifras actuales y el procedimiento exacto en una sola pantalla.

Flujo de revisión tipo code review para textos técnicos

Otro clásico problema de cualquier wiki son los cambios accidentales sin control. En Confluence cualquiera con permisos de edición puede modificar un comando crítico o borrar una variable clave sin que nadie se entere.

En Oxynote puedes activar el modo de aprobación obligatoria (Review Workflow) para las páginas. Cualquier edición genera un borrador (draft branch). Al enviarlo a revisión, el sistema construye un diff visual bloque a bloque (block-level diff) que resalta:

  • qué párrafos de texto han cambiado;
  • qué campos en los esquemas de API se han añadido o eliminado;
  • cómo se ha ajustado la consulta PromQL en el bloque de monitorización.

La fusión a la rama principal del runbook solo ocurre tras la aprobación explícita de un revisor asignado, llevando el rigor habitual de Git al mundo de la documentación.

Control de vigencia mediante Freshness Hooks

Para que los manuales no acaben convertidos en un cementerio digital, Oxynote incorpora Freshness Hooks. Puedes vincular un bloque o documento a commits de un repositorio en GitHub, a la publicación de una nueva etiqueta de contenedor o a una fecha límite. Si el microservicio se actualiza y nadie ha revisado el runbook en más de tres meses, el sistema avisa automáticamente al autor de que toca ponerlo al día.

Arranque rápido y definición declarativa de bloques

Oxynote se distribuye como un contenedor autónomo en Go y TypeScript sin dependencias en la nube:

# Arranque del contenedor con volumen local para persistencia de datos
docker run -d --name oxynote \
  -p 8080:8080 \
  -v oxynote_data:/oxynote/data \
  --restart unless-stopped \
  ghcr.io/oxynote/oxynote:latest

# El panel web queda disponible en http://localhost:8080
# Acceso por defecto: admin@example.com / oxynote-admin-1234

Dentro de la página, un bloque de métricas en vivo se describe con una estructura declarativa que une las consultas de monitorización con la explicación técnica:

block_type: live_metric_chart
chart_type: time_series
title: "Частота запросов к сервису авторизации (HTTP 2xx vs 5xx)"
sources:
  - id: prometheus_cluster
    type: prometheus
    url: "http://prometheus.internal:9090"
    query: "sum(rate(http_requests_total{job="auth-api"}[5m])) by (status)"
    legend: "HTTP {{status}}"
  - id: db_pool
    type: postgresql
    dsn_secret: "POSTGRES_METRICS_DSN"
    query: "SELECT now() AS time, count(*) AS active_connections FROM pg_stat_activity WHERE state = "active";"
    legend: "Active DB Connections"
display:
  unit: "req/s"
  thresholds:
    warning: 500
    critical: 1000
explanation: |
  Если частота ошибок HTTP 5xx превышает 5% от общего объема трафика более 3 минут подряд,
  проверьте загрузку пула соединений PostgreSQL по графику справа и выполните регламент Runbook #12.

Oxynote todavía no sustituye por completo a Grafana: no tiene agregación de logs al estilo de Loki ni un motor complejo de enrutamiento de alertas. Pero para runbooks y documentación de arquitecturas de microservicios, este híbrido entre wiki y monitorización ahorra minutos valiosos cuando el entorno de producción arde.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 2