{
  "index": 156,
  "slug": "editorial-2023-09-practice-telemetry-signals",
  "title": "Trace ID, метрика и лог: как связать сигналы без высокой cardinality",
  "excerpt": "Практический договор для распределённого запроса: trace ID связывает путь и событие, метрика считает малый набор классов, а лог сохраняет контекст отказа.",
  "contentHtml": "<p>На графике выросли ошибки авторизации. В журнале есть сообщения об отказе. В трассировке виден тот же endpoint, но инженер не может доказать, что три наблюдения относятся к одному запросу. Он тратит время на ручной поиск и может увеличить timeout или retry, не устранив причину. Цена ошибки — лишняя нагрузка, задержка расследования и решение по несвязанным данным.</p>\n<p>Быстрый ремонт — добавить trace ID во все метрики, а в лог оставить длинный текст. Связь одного запроса с графиком станет возможной, но метрика перестанет быть хорошим агрегатом. Число уникальных series будет расти вместе с числом запросов. Корреляция должна жить в trace и логах, а метрика должна отвечать на вопрос о классе событий.</p>\n<h2>Тезис: каждому сигналу — свой вопрос</h2>\n<p>Trace описывает путь операции через компоненты. Metric показывает число, долю или распределение во времени. Log фиксирует отдельное событие и его контекст. OpenTelemetry называет их разными сигналами, потому что у них разные модели данных и способы поиска.</p>\n<p>Общий trace ID связывает span одного распределённого пути. Span ID уточняет конкретный шаг. Лог может содержать оба значения и имя события. Метрика должна использовать поля с небольшим заранее известным набором значений: шаблон маршрута, результат и имя сервиса. Идентификатор запроса, пользователя, заказа и необработанный URL в этот набор обычно не входят.</p>\n<h2>Механизм связи</h2>\n<p>Клиент отправляет запрос в gateway. Gateway принимает или создаёт trace context и передаёт его дальше. Сервис оплаты создаёт дочерний span. При отказе сервис записывает событие в лог с trace ID и span ID шага оплаты. Отдельно он увеличивает счётчик отказов с labels <code>service</code>, <code>route</code> и <code>outcome</code>. По метрике видно, что класс отказа растёт. По trace ID можно найти конкретный путь. По записи события можно понять, что произошло внутри шага.</p>\n<p>Сигналы не связываются автоматически. Пропагатор может быть не настроен, лог может потерять контекст, sampling может не сохранить нужный trace, а индекс может скрыть поле поиска. Договор задаёт ожидаемую связь. Проверка должна показать, где она рвётся.</p>\n<table><thead><tr><th>Сигнал</th><th>Вопрос</th><th>Допустимые поля</th><th>Не следует добавлять</th></tr></thead><tbody><tr><td>Trace</td><td>Какой путь прошёл запрос?</td><td>trace ID, span ID, service, operation</td><td>Свободный текст вместо структуры</td></tr><tr><td>Metric</td><td>Как меняется класс событий?</td><td>service, route template, outcome</td><td>trace ID, request ID, user ID, order ID</td></tr><tr><td>Log</td><td>Что произошло на одном шаге?</td><td>trace ID, span ID, event name, безопасные attributes</td><td>Секреты, токены и лишние персональные данные</td></tr></tbody></table>\n<figure><img src=\"/assets/editorial/2023/telemetry-signals-2023-correlation-map.svg\" alt=\"Схема связи trace ID, span, лога и метрики с ограниченным набором labels\"><figcaption>Общий trace ID связывает путь и событие, а метрика сохраняет только агрегируемые labels.</figcaption></figure>\n<h2>Учебный пример</h2>\n<p>Ниже показана форма данных для одного учебного отказа. Имена с префиксом <code>demo-</code> не представляют реальные запросы, пользователей, задержки или результаты работы сервиса. Пример проверяет только границы между сигналами.</p>\n<pre><code>const trace = { traceId: 'demo-trace-001', spans: [{ spanId: 'demo-span-gateway', service: 'gateway', operation: 'checkout' }, { spanId: 'demo-span-payment', service: 'payment', operation: 'authorize' }] }; const logEvent = { traceId: trace.traceId, spanId: 'demo-span-payment', eventName: 'payment.authorization.rejected', attributes: { reasonClass: 'demo-limit', retryable: false } }; const metric = { name: 'payment_authorization_total', value: 1, labels: { service: 'payment', route: 'checkout', outcome: 'rejected' } };</code></pre>\n<p>В примере trace ID повторяется в trace и log. Он не попадает в labels метрики. Поля <code>reasonClass</code> и <code>retryable</code> объясняют событие, но не становятся dimensions автоматически. В рабочей системе имена и состав полей нужно согласовать с владельцами сервиса, требованиями безопасности и возможностями хранилища. Этот фрагмент не создаёт telemetry и не доказывает работу экспортера.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<table><thead><tr><th>Симптом</th><th>Причина</th><th>Проверка</th><th>Действие</th></tr></thead><tbody><tr><td>График показывает всплеск, но запрос не найти</td><td>Нет устойчивого перехода от metric к trace</td><td>Выбрать один отказ и проверить его trace ID в логах</td><td>Оставить labels агрегируемыми, а корреляцию добавить в log/span</td></tr><tr><td>Число series растёт почти с каждым запросом</td><td>В labels попал trace ID или другой уникальный идентификатор</td><td>Посчитать словари значений по каждой label и сравнить с числом запросов</td><td>Удалить request-like label и заменить его малым классом</td></tr><tr><td>Trace есть, но событие не объясняет отказ</td><td>Лог содержит только текст или другой span ID</td><td>Сверить trace ID, span ID, имя события и обязательные attributes</td><td>Записывать структурированное событие на том же шаге</td></tr><tr><td>Связь работает только иногда</td><td>Контекст теряется на границе сервиса или при sampling</td><td>Проверить propagation на входе и выходе</td><td>Исправить границу передачи; не маскировать пробел новой label</td></tr></tbody></table>\n<h2>Порядок внедрения</h2>\n<ol><li>Назовите один пользовательский путь и один отказ. Не начинайте с полного набора endpoint.</li><li>Для каждого сигнала запишите его вопрос. Поле без ясного вопроса уберите из договора.</li><li>Определите trace ID и span ID, которые должны попасть в контекст и событие. Проверьте, что они не содержат пользовательских данных.</li><li>Составьте список metric labels. Для каждой укажите допустимый словарь или правило нормализации. Используйте шаблон маршрута вместо сырого URL.</li><li>Проверьте отрицательные случаи: другой trace ID, неверный span ID, отсутствующее обязательное поле и попытка добавить уникальный ID в метрику.</li><li>Запустите проверку в разрешённой среде и сохраните ссылку на trace, запись события и график. Учебный объект подтверждает только форму данных; рабочее подтверждение требует реальной системы.</li></ol>\n<h2>Отрицательный путь важнее счастливого</h2>\n<p>Если gateway передал trace context, а payment создал новый trace вместо дочернего span, оба сигнала выглядят корректно по отдельности. Поиск по одному ID ничего не даст. Если лог записал trace ID, но указывает span gateway вместо span с отказом, инженер попадёт в начало пути и пропустит причину. Если метрика получила <code>user_id</code>, она может показать нужный случай, но ценой неконтролируемого числа комбинаций и лишнего раскрытия данных.</p>\n<p>Проверяйте эти случаи специально. Сравните входной и исходящий context на каждой границе. Сопоставьте span ID события с операцией, где произошёл отказ. Отдельно проверьте отказ без trace: пустая строка не должна смешивать разные случаи. Если связь потеряна, исправьте propagation. Не маскируйте пробел новой label.</p>\n<h2>Ограничения</h2>\n<p>Небольшой набор labels не гарантирует низкую стоимость хранения. Итог зависит от числа сервисов, маршрутов, окружений, времени хранения и запросов к backend. Удаление trace ID из метрики не решает проблему, если в labels остаются сырые URL, тексты ошибок или идентификаторы заказов. Нужен отдельный обзор cardinality и доступа к данным.</p>\n<p>Trace sampling может сохранить не каждый запрос. Логирование тоже может быть ограничено уровнем, фильтрами или политикой персональных данных. Поэтому отсутствие trace по графику не доказывает отсутствие ошибки. В критичном потоке метрика должна фиксировать класс отказа, а лог — безопасный контекст для следующей проверки.</p>\n<h2>Критерий готовности</h2>\n<p>Договор готов, когда для выбранного пути выполнены четыре условия: один запрос сохраняет общий trace ID через нужные границы; событие отказа содержит тот же trace ID и span ID правильного шага; метрика группируется только по описанным labels; отрицательная проверка обнаруживает mismatch и уникальные идентификаторы в labels. Результат должен воспроизводиться по ссылкам на конкретный trace, лог и график в разрешённой среде. Если условие не выполнено, связь сигналов ещё не доказана.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://opentelemetry.io/docs/concepts/signals/\" target=\"_blank\" rel=\"noopener\">OpenTelemetry: Signals</a> — официальное описание traces, metrics и logs.</li><li><a href=\"https://opentelemetry.io/docs/specs/otel/trace/api/\" target=\"_blank\" rel=\"noopener\">OpenTelemetry Trace API</a> — описание SpanContext, TraceId и SpanId.</li><li><a href=\"https://www.w3.org/TR/trace-context/\" target=\"_blank\" rel=\"noopener\">W3C Trace Context</a> — стандарт передачи trace-контекста между компонентами.</li></ul>"
}