Наблюдаемость: спаны, метрики, логи

Руководство пользователя к ТЗ Р7 и [С §15.5]. Решения: D-5240..D-5259 в docs/decisions.md; устройство — docs/ARCHITECTURE.md, раздел «Наблюдаемость».

Без настройки ничего не экспортируется и не открывается: спаны не записываются (проверка одного атомарного флага), порта метрик нет. Внутрипроцессный вызов rpc остаётся в пределах 0.2–0.3 мкс.

Быстрый старт#

# спаны, метрики и логи в OpenTelemetry Collector по gRPC
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 OTEL_SERVICE_NAME=shop ./shop

# Prometheus: страница http://127.0.0.1:9464/metrics
./shop --metrics-listen 127.0.0.1:9464

Адрес: http://host:4317 (без TLS, h2c), https://host:4317 (TLS, системные корневые сертификаты) или host:port; порт по умолчанию 4317. Бездельничающий --metrics-listen 9464 слушает только 127.0.0.1; чтобы открыть наружу, укажите 0.0.0.0:9464 (страница не защищена — ставьте за фаервол).

Спаны#

Автоматически создаются спаны:

Статус ERROR ставится при любом исходе rpc, кроме ok (в том числе при доменной ошибке; сообщение — имя исхода), у HTTP-сервера — при коде 5xx, у HTTP-клиента — при 4xx/5xx и при отсутствии ответа.

Распространение контекста#

• gRPC: заголовок метаданных traceparent (W3C Trace Context, версия 00); совместимо со всеми OpenTelemetry-SDK. Прежний x-oxl-trace продолжает отправляться и читаться.
• HTTP (std.http): сервер читает traceparent запроса, клиент добавляет его в исходящие запросы.
• ctx.traceId (32 hex-цифры, одинаков во всех процессах) и ctx.spanId (16 hex-цифр, спан, в котором выполняется код) доступны в обработчиках rpc.
• Дочерние задачи (spawn, scope) наследуют текущий спан.

Выборка#

Решение принимается один раз, у корня трассы, по хэшу traceId: все процессы, увидевшие один идентификатор, решают одинаково; дальше решение родителя (флаг 01/00 в traceparent) уважается всеми. Вызов с отброшенной трассой всё равно несёт traceId и ctx.spanId, но спаны не записываются.

• @trace(sample: 0.1) на rpc — доля выборки для трасс, корнем которых является этот rpc; 0.0 — не трассировать, 1.0 — всегда.
• Иначе — доля процесса: --trace-sample / OXL_TRACE_SAMPLE. Значение «кластера» из §15.5 сегодня это значение процесса (см. D-5241, вопрос заказчику).

Свои спаны#

use std.obs { span, metric, log }

fn charge(order: Order) io {
  span.with("charge") {                 // закрывается при выходе, в том числе при панике
    let s = span.start("antifraud")     // или вручную
    s.set("order", "{order.id}")
    s.setInt("amount", order.cents)
    if s.recording() { /* дорогое вычисление атрибута */ }
    s.setError("score too high")          // статус ERROR
    s.end()
  }
}

Закрывайте спаны в обратном порядке открытия и в той же задаче. Если трассировка выключена или трасса не выбрана, span.start ничего не стоит.

Метрики#

let paid = metric.counter("orders_paid_total", help: "Paid orders.", labels: {"shop": "eu"})
paid.inc()
let queue = metric.gauge("queue_length")
queue.set(12.0); queue.dec()
let size = metric.histogram("payload_bytes", buckets: [64.0, 1024.0, 65536.0])
size.observe(300.0)

• Имя — имя Prometheus ([a-zA-Z_:][a-zA-Z0-9_:]*), счётчикам принято окончание _total. Неверное имя или метка, а также имя, уже занятое метрикой другого вида, сообщается один раз на stderr, а обработчик ничего не делает.
• Одинаковые имя и метки — одна и та же серия. Создавайте обработчик один раз и храните его: поиск идёт под мьютексом, увеличение — атомарная операция.
• Без buckets гистограмма имеет корзины задержек в секундах: 0.0001 … 10.

Встроенные метрики (/metrics и OTLP):

Задержка rpc измеряется для первых 256 вызовов метода и далее для каждого 16-го (с весом 16), счётчики вызовов точны (D-5254).

Формат страницы — Prometheus text 0.0.4. GET /metrics — 200, остальные пути — 404, не-GET — 405.

Логи#

log.info("order {id} paid") внутри обработчика rpc или спана несёт идентификаторы:

2026-11-03T15:04:05.250Z INFO  order 42 paid id=42 trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7
{"ts":"…","level":"info","msg":"order 42 paid","trace_id":"4bf9…","span_id":"00f0…","fields":{"id":"42"}}

С OTEL_LOGS_EXPORTER=otlp записи уходят и по OTLP (с trace_id/span_id в самой записи, поля — атрибутами).

Экспорт: гарантии и потери#

• Очередь ограничена (OTEL_BSP_MAX_QUEUE_SIZE); при переполнении новые спаны отбрасываются и учитываются в oxl_telemetry_spans_dropped_total. Горячий путь никогда не ждёт сети.
• Пакеты уходят отдельной задачей раз в OTEL_BSP_SCHEDULE_DELAY или сразу, когда набрался пакет. Недоступный сборщик не мешает программе: пакет отбрасывается и считается, первые три сбоя пишутся в stderr.
• При нормальном завершении (и после SIGTERM, после дренажа) остаток очередей отправляется синхронно, не дольше секунды на запрос.

Проверка#

• scripts/bench.py --rpc — задержка внутрипроцессного вызова (с выключенной трассировкой и с включённой, но отброшенной выборкой).
• ctest telemetry_otlp: два процесса, свой mock-сборщик OTLP, проверка общего traceId, связи «родитель–потомок» клиент → сервер, /metrics, логов с идентификаторами и выборки.

Инспектор#

--inspect-ui[=addr] (по умолчанию 127.0.0.1:8090) открывает в узле веб-интерфейс состояния кластера [С III.8]: одна встроенная страница и JSON-API GET /api/<раздел> (nodes roles config dynconf services actors sagas streams traces logs rights), POST /api/action (заголовок X-Oxl-Inspect: 1). Любой узел показывает весь кластер: локальные данные других узлов запрашиваются по межузловому каналу. Тот же API — gRPC-сервис oxl.Inspect (runtime/proto/oxl/inspect.proto) на порту узла; oxl inspect --cluster host:port поднимает страницу локально. Буферы трасс и логов — 64 МБ / 15 мин на узел с UI (или на всех узлах с OXL_INSPECT_BUFFERS=1). Доступ — роль Admin или inspect (JWT), действия — отдельные роли, всё пишется в oxl.audit; в профиле dev с --insecure-dev локальный пользователь — оператор. Решения: D-6400..D-6410.

Трассы из командной строки, журнал запросов, A/B#

• oxl trace <traceId> --cluster host:port печатает трассу из буферов узлов (раздел traces инспектора): дерево спанов по узлам и граф вызовов между ними.
• oxl trace --record f.oxlrec --cluster host:port --for 60s [--service S] записывает входящие unary-rpc всех узлов (метод, запрос, метаданные без учётных данных, пользователь, трасса, время, ответ или ошибка) в журнал .oxlrec (формат — docs/oxlrec.md); oxl replay f.oxlrec|<traceId> --cluster host:port отправляет их снова и сравнивает ответы.
• A/B-эксперименты ([С §18.5]): код узнаёт вариант через ab.variant("имя") (std.ab); oxl test --kind ab прогоняет записанный трафик, oxl ab start|status|stop работает в кластере. Встроенные метрики вариантов — latency.p50/p95/p99/mean (время обработчика, мс) и error_rate; пользовательские — любые метрики std.obs по имени. Значимость — t-тест Уэлча для средних и z-тест для долей, p < 0,05 при ≥ 100 запросах на вариант. Решения: D-6850..D-6866.

Исходник: docs/observability.md