Метрики backend-приложений¶

Требования этого документа применяются к метрикам backend-приложений, API, worker-, consumer-процессов и data pipelines. Уровни обязательности определены в корневом README.md.

Сбор метрик приложения является рекомендуемой возможностью. Требования OBS-MET-002–OBS-MET-010 применяются только если проект выбрал этот канал либо явно использует метрики приложения как источник SLI или release gate.

OBS-MET-001. OpenTelemetry и маршрут доставки¶

Уровень: SHOULD

Применяется к: решению о сборе метрик приложения

Приложению следует собирать метрики через OpenTelemetry API/SDK и передавать их по OpenTelemetry Protocol (OTLP) в OpenTelemetry Collector с последующей доставкой в OpenObserve.

При выборе этого канала не следует отправлять метрики прямо в OpenObserve или связывать прикладной код с API OpenObserve.

Обоснование¶

Стандартный API и промежуточный Collector отделяют инструментирование от конкретного хранилища и унифицируют маршрут метрик и трасс.

Проверка¶

review зависимостей и конфигурации exporter;
integration-тест маршрута приложение → OTLP → OpenTelemetry Collector → OpenObserve;
проверка отсутствия прямого exporter в OpenObserve.

Исключения¶

Проект MAY не собирать метрики приложения без ADR, если его обязательные SLI, release gates и диагностика обеспечены другими сигналами.

OBS-MET-002. Версия и идентификация ресурса¶

Уровень: MUST

Применяется к: каждому потоку метрик приложения

Метрики должны использовать зафиксированную проектом версию OpenTelemetry Semantic Conventions по OBS-TRACE-002.

Resource должен содержать service.name, service.version и deployment.environment.name. Значения и семантика должны совпадать с трассами, диагностическими и аудит-логами, а также событиями ошибок. service.name не должен содержать hostname, pod ID или другой идентификатор экземпляра.

Обоснование¶

Общая версия схемы и идентификация позволяют сопоставлять сигналы и агрегировать экземпляры одного выпуска без дублирования временных рядов.

Проверка¶

проверка версии SDK и Semantic Conventions;
запрос по resource-атрибутам в OpenObserve;
сопоставление значений между метриками, трассами, логами и GlitchTip.

Исключения¶

Не допускаются.

OBS-MET-003. Метрики результата и нагрузки¶

Уровень: MUST

Применяется к: каждому типу входящей операции API, consumer и worker

Для типа входящей операции должны быть доступны:

количество завершённых операций с классификацией результата;
длительность завершённых операций в виде histogram;
количество выполняемых операций;
количество принятой работы, если оно отличается от количества завершённой.

Имена, единицы, типы инструментов и стандартные атрибуты должны следовать зафиксированной версии OpenTelemetry Semantic Conventions. Метрика завершения должна записываться ровно один раз на логическую попытку обработки независимо от успешного или неуспешного результата.

Обоснование¶

Число операций, ошибки, задержка и конкурентная нагрузка образуют минимальный набор для оценки пользовательского результата и пропускной способности.

Проверка¶

contract-тест успешного, ошибочного, отменённого и просроченного результата;
сопоставление количества тестовых операций с точками метрик;
проверка типа инструмента, единицы и buckets histogram.

Исключения¶

Метрика принятой работы может отсутствовать, если одна принятая операция всегда однозначно соответствует одной попытке завершения.

OBS-MET-004. Метрики зависимостей и насыщения¶

Уровень: MUST

Применяется к: обязательным внешним зависимостям и ограниченным ресурсам процесса

Для обращения к обязательной внешней зависимости должны быть доступны количество, длительность и технический результат вызовов. Для каждого ограниченного ресурса, способного влиять на обработку, должна быть доступна метрика насыщения: занятые элементы, длина очереди, ожидание или доля использования в соответствии с моделью ресурса.

Процесс должен предоставлять применимые runtime-метрики CPU, памяти, сборки мусора, thread или event loop через поддерживаемое OpenTelemetry инструментирование.

Обоснование¶

Метрики зависимостей и насыщения отличают недостаток ресурсов от ошибки прикладной логики и позволяют обнаружить деградацию до полного отказа.

Проверка¶

нагрузочный тест каждого ограниченного пула и очереди;
fault-injection тест обязательной зависимости;
проверка наличия применимых runtime-метрик в OpenObserve.

Исключения¶

Неприменимая runtime-метрика может отсутствовать; проект должен уметь указать какой наблюдаемый ресурс или механизм в выбранном runtime отсутствует.

OBS-MET-005. Единая классификация результата¶

Уровень: MUST

Применяется к: атрибутам результата и ошибки метрик

Технический успех, техническая ошибка, timeout, отмена, корректный клиентский отказ и ожидаемый бизнес-результат должны различаться, если они возможны для операции. Ожидаемый бизнес-результат и корректный клиентский отказ не должны автоматически учитываться как техническая ошибка.

Класс ошибки должен определяться стабильным типом или кодом, а не текстом сообщения. Семантика результата должна совпадать со статусом span по OBS-TRACE-007 и классификацией события ошибки по OBS-ERR-003.

Обоснование¶

Единая классификация предотвращает расхождение error rate между метриками, трассами и системой сбора ошибок.

Проверка¶

unit-тест таблицы классификации результатов;
сквозной тест одной операции во всех сигналах;
проверка запросов error rate для каждого класса результата.

Исключения¶

Проект может объединять классы, которые невозможно различить в контракте наблюдаемой границы, через утверждённый ADR.

OBS-MET-006. Ограниченная кардинальность¶

Уровень: MUST

Применяется к: именам метрик и их атрибутам

Имя метрики и набор ключей атрибутов должны быть стабильными и конечными. Значения атрибутов должны иметь заранее ограниченное множество либо контролируемую верхнюю границу.

В атрибутах запрещены trace_id, span_id, request_id, correlation_id, идентификаторы пользователей и сущностей, необработанные URL, query string, текст SQL, текст ошибки, stack trace, timestamp и случайные значения. Маршрут HTTP должен представляться шаблоном маршрута, а не фактическим путём.

Обоснование¶

Высокая кардинальность создаёт неограниченное число временных рядов, повышает стоимость и может нарушить работу платформы метрик.

Проверка¶

статическая проверка вызовов инструментирования;
тест динамических URL, ошибок и идентификаторов;
анализ числа рядов и кардинальности атрибутов в OpenObserve.

Исключения¶

Exemplar может содержать разрешённую OpenTelemetry-связь с trace, если OpenObserve хранит её отдельно от набора атрибутов временного ряда.

OBS-MET-007. Защита данных¶

Уровень: MUST

Применяется к: именам, описаниям и атрибутам метрик

Метрики не должны содержать секреты, аутентификационные данные, персональные данные, полные платёжные данные или содержимое запросов, ответов и сообщений. Фильтрация должна выполняться до передачи метрики из процесса.

Обоснование¶

Значения метрик индексируются и многократно агрегируются; удаление чувствительного значения после экспорта не устраняет его распространение.

Проверка¶

автоматический тест с маркерами чувствительных данных;
security review инструментирования и resource-атрибутов;
контролируемое сканирование атрибутов в OpenObserve.

Исключения¶

Не допускаются для секретов, аутентификационных и полных платёжных данных. Обезличенные агрегаты персональных данных требуют утверждённого контракта классификации.

OBS-MET-008. Описание пользовательских метрик¶

Уровень: MUST

Применяется к: метрике, не определённой OpenTelemetry Semantic Conventions

Пользовательская метрика должна иметь в репозитории проекта стабильное имя, описание наблюдаемой величины, единицу, тип инструмента, допустимые атрибуты и правило записи. Владение метрикой по умолчанию совпадает с владением компонентом; отдельный владелец для каждой метрики не требуется.

Counter должен быть монотонным и не использоваться для текущего значения. Текущее значение должно измеряться gauge или эквивалентным observable instrument. Histogram должен иметь границы, соответствующие измеряемому диапазону и запросам Service Level Indicator (SLI).

Изменение смысла существующего имени запрещено; несовместимая семантика должна получить новое имя с управляемой миграцией dashboards и alerts.

Обоснование¶

Явный контракт предотвращает несовместимую агрегацию и скрытое изменение смысла временного ряда.

Проверка¶

сопоставление кода инструмента с описанием метрики;
тест монотонности, единицы, правила записи и histogram boundaries;
review миграции запросов при изменении схемы.

Исключения¶

Не допускаются для пользовательских метрик production.

OBS-MET-009. Данные для SLI¶

Уровень: MUST

Применяется к: production-операции, для которой определён SLI по OPS-SLO-001

Метрики должны предоставлять числитель, знаменатель, распределение задержки и признаки насыщения, необходимые для SLI, определённых по OPS-SLO-001. Фильтры должны позволять исключить health checks, служебный и синтетический трафик либо классифицировать их отдельно.

Изменение имени, атрибута или histogram boundaries не должно нарушать действующую формулу SLI без одновременной версионируемой миграции запроса.

Обоснование¶

SLI нельзя надёжно вычислить, если метрика не различает область и результат учитываемых операций.

Проверка¶

сопоставление инструментов с формулами SLI;
тест успешного, ошибочного и исключённого трафика;
compatibility test изменения схемы метрик.

Исключения¶

Численные цели и alert регулируются OPS-SLO-002–OPS-SLO-004.

OBS-MET-010. Ограничение влияния экспорта¶

Уровень: MUST

Применяется к: OpenTelemetry SDK и OTLP exporter метрик

Экспорт должен быть асинхронным, пакетным и ограниченным по памяти, размеру очереди, числу повторов и времени ожидания. Интервал экспорта и temporality должны быть явно настроены и совместимы с Collector и запросами OpenObserve.

Недоступность или замедление Collector и OpenObserve не должны изменять результат бизнес-операции, блокировать её или приводить к неограниченному потреблению ресурсов. Потеря метрик и ошибка exporter должны быть наблюдаемы без рекурсивного создания метрик тем же неисправным каналом.

Обоснование¶

Метрики не должны становиться синхронной критической зависимостью приложения.

Проверка¶

тест недоступности и замедления Collector;
нагрузочный тест очереди и памяти SDK;
тест восстановления экспорта без перезапуска процесса.

Исключения¶

Не допускаются.