4.8 KiB
Контракт наблюдаемости
Ниже логические сигналы. Допустимы стандартные semantic conventions выбранного SDK и их native metric names: зафиксируйте соответствие в REPORT.md, dashboard обязан ссылаться на реально существующие имена/единицы. Переименование SDK не повод дублировать одну метрику двумя инструментами. Версии SDK, semantic conventions, Collector distribution и backend закрепляются в решении.
| Сигнал | Минимальные поля/измерения | Уровень |
|---|---|---|
| HTTP requests | method, route template, status class; counter | 3 |
| HTTP duration | histogram в секундах или документированное преобразование из ms | 3 |
| Jobs processed / failed | job type, outcome, counter | 3 |
| Job processing duration | job type, outcome, histogram | 3 |
| API и worker logs | timestamp, severity, service.name, event, trace_id, span_id при активном span | 3 |
| API и worker traces | реальные server/consumer spans, duration, outcome; не искусственный статический trace | 3 |
| Queue depth / oldest job age | queue name, количество / секунды | 4 |
| Pool/saturation | DB pool used/waiting, worker busy/capacity, process/container CPU/RAM | 4 |
| Сквозная связь upload → publish → consume → S3/DB | W3C traceparent/tracestate; parent-child или link по выбранной семантике | 4 |
| End-to-end time to ready | от durable acceptance до публикации ready, histogram | 4 |
Resource attributes: service.name (messenger-api / messenger-worker), service.version, service.instance.id, deployment.environment.name=lab. Список имён может отличаться, если явно сопоставлен. X-Request-Id коррелирует HTTP-ошибку с логом; trace_id — не замена всех request IDs.
Не labels метрик: user_id, chat_id, message_id, attachment_id, request_id, raw URL, filename, текст. Для маршрута используйте /api/v1/chats/{chat_id}/messages, не реальный UUID. В логах/трассах допустимы ограниченные технические ID для учебных синтетических данных, если обоснована необходимость; пароли, Authorization, session token, body сообщения, картинка, private key и signed URL запрещены.
Для HTTP error ratio заранее определите numerator/denominator: например 5xx/все бизнес-запросы, исключая health; не смешивайте неверный пароль клиента с отказом БД. p95 агрегируется из histogram buckets всех нужных реплик, а не средних p95. Границы buckets должны соответствовать ожидаемым задержкам. Backlog — не queue processing latency.
В Git находятся Collector config, backend configs, datasources/dashboard provisioning, dashboard JSON и на 4 alert rules. У alerts есть условие, окно, порог, for при необходимости, описание и локальный runbook. Отправка сообщений в почту/мессенджер не требуется.
Минимальные контролируемые инциденты для 4: (1) остановить worker и увидеть рост возраста задач; (2) сделать DB медленной/недоступной и отличить её от медленного HTTP handler по trace/метрикам. После восстановления backlog уменьшается, alerts resolved. Третий сценарий — недоступность backend telemetry: SDK/Collector ограничивают RAM/очередь, API сохраняет работу, потери telemetry считаются и объясняются.
Collector — получатель/обработчик/экспортёр, не долговременная БД. Grafana — интерфейс и запросы к источникам. Логи можно отправлять OTLP в совместимый backend; не закладывайте удалённый/устаревший exporter без проверки текущей сборки. См. Collector configuration, Trace Context и histograms.