Вспомни, как обычно выглядит разбор сложной аварии в твоём проекте. В одной вкладке браузера открыт дашборд Grafana с графиками всплеска пятисотых ошибок и загрузки пула соединений. Во второй вкладке — регламент действий (runbook) в Notion или корпоративном Confluence, написанный год назад уволившимся коллегой.
Ты смотришь на график и пытаешься понять: 400 активных соединений с базой данных — это нормальная пиковая нагрузка или уже катастрофический затор? В Grafana это пояснить негде, кроме крошечной плашки описания панели. А попытка встроить дашборд через iFrame в корпоративную wiki обычно разбивается об авторизацию и полное отсутствие версионирования.
Создатели популярной библиотеки ttlcache решили преодолеть этот разрыв контекста и выпустили открытый проект Oxynote под лицензией Apache 2.0. Концепция получила название «дышащей документации» (breathing docs) — базы знаний, где живые метрики и текст регламентов живут рука об руку.
Живые блоки метрик прямо в тексте
Вместо статичных скриншотов или внешних фреймов Oxynote использует нативные блоки Live Metrics. Внутрь обычного абзаца документации встраиваются графики временных рядов (time series), гистограммы или круговые шкалы (gauges).
Каждый блок связывается напрямую с источником данных: поддерживается выполнение PromQL-запросов к Prometheus и прямой SQL к реляционным базам данных (PostgreSQL, MySQL, MariaDB). Под графиком ты сразу формулируешь критерии нормы: «Если частота ошибок превышает 5% более 3 минут подряд, выполните следующие шаги». Инженер видит и текущие цифры, и точный порядок действий в одном окне.
Модель код-ревью для технических текстов
Ещё одна классическая боль документации — случайные неконтролируемые правки. В Confluence любой сотрудник с правами редактирования может поправить критическую команду или удалить важную переменную.
В Oxynote страницы можно переводить в режим обязательного согласования (Review Workflow). Любые изменения формируют черновик (draft branch). При отправке на согласование система строит наглядный поблочный diff (block-level diff), подсвечивая:
- какие абзацы текста изменились;
- какие поля в схемах API были добавлены или удалены;
- как скорректирован текст PromQL-запроса в блоке мониторинга.
Слияние в основную ветку регламента происходит только после явного подтверждения назначенным ревьюером, перенося привычные стандарты надёжности Git в мир документации.
Чтобы регламенты не превращались в цифровое кладбище, Oxynote предлагает хуки свежести (Freshness Hooks). Блок или документ можно привязать к коммитам в GitHub-репозитории сервиса, выходу нового тега контейнера или календарному сроку. Если микросервис обновился, а регламент никто не открывал более трёх месяцев, система автоматически уведомит автора о необходимости ревизии.
Быстрый старт и декларативное описание блоков
Oxynote поставляется в виде самодостаточного контейнера на Go и TypeScript и не требует внешних облачных зависимостей:
# Запуск контейнера с локальным томом для постоянного хранения данных
docker run -d --name oxynote \
-p 8080:8080 \
-v oxynote_data:/oxynote/data \
--restart unless-stopped \
ghcr.io/oxynote/oxynote:latest
# Веб-панель доступна по адресу http://localhost:8080
# Вход по умолчанию: admin@example.com / oxynote-admin-1234
Внутри страницы блок с живыми метриками описывается декларативной структурой, связывающей запросы мониторинга с текстовой инструкцией:
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 пока не заменяет Grafana полностью — в нём нет агрегации логов уровня Loki или сложного движка маршрутизации алертов. Но для runbook-инструкций и описания микросервисной архитектуры этот гибрид вики и мониторинга экономит драгоценные минуты при устранении боевых инцидентов.