✻ Урок 8.8 · Тема 8: Наблюдаемость
Трейсинг: OpenTelemetry и Tempo
Содержание урока
Как работать с кодом и когда идти дальше
Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:
- Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
- Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
- Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.
Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.
Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.
Зачем это нужно
Метрики говорят, что запросы стали медленными. Логи говорят, что что-то пошло не так. Но ни то ни другое не отвечает на вопрос «где именно этот запрос потерял 900 мс: в приложении, в базе или по дороге». Для этого есть трейс (trace, «след»): запись пути одного запроса по всем компонентам, с длительностью каждого шага. Это как маршрутный лист посылки: на каждом складе ставят штамп «принял в 10:05, отдал в 10:07», и по листу видно, где посылка пролежала дольше всего. Без трейса ты знаешь, что доставка медленная, но не знаешь, на каком складе. Один такой штамп (один шаг) называется спан (span, «отрезок»), а весь лист целиком трейс.
Вот как выглядит такой «маршрутный лист» одного запроса «Заметок», который шёл 940 мс:
Трейс a1f3c9... GET /notes всего 940 мс
GET /notes |████████████████████████████████| 940 мс
разбор запроса |█ | 12 мс
запрос к базе данных | ██████████████████████████████| 905 мс
сборка ответа | █| 23 мс
Верхняя строка весь запрос, строки с отступом его шаги. Почти всё время (905 из 940 мс) съел запрос к базе, значит искать нужно там, а не в приложении.
На работе трейсинг включают, когда сервисов больше двух и «тормозит где-то» перестаёт быть диагнозом. Даже для одного сервиса с базой данных трейс сразу показывает, сколько времени заняли SQL-запрос и сама логика приложения.
Шаг проекта: «Заметки» получают версию v7 (образ 0.7.0) с OpenTelemetry, в логах появляется trace_id, а в стеке мониторинга поднимаются Tempo и приём OTLP в Alloy. Расшифровка: OpenTelemetry (OTel) это общий стандарт и набор библиотек, которые учат программу записывать метрики, логи и трейсы в одном формате. trace_id это номер запроса: по нему все спаны одного запроса собираются вместе. OTLP (OpenTelemetry Protocol) это формат и протокол, которым программа отправляет спаны дальше, а Tempo (от Grafana Labs) это хранилище, где трейсы лежат и откуда ищутся. Alloy (агент, который ты настроил в уроке 8.7) по пути принимает спаны и передаёт в Tempo. Всё это подробно разберём ниже.
Что нужно знать
- Урок 2.4: HTTP - заголовки запроса, из них будет состоять контекст трассировки
- Урок 4.5: Compose и PostgreSQL - сеть
notes-net, обращение приложения к БД - Урок 8.2: Prometheus - как выглядит стек
monitoring/compose.yml, гистограмма задержек - Урок 8.6: Grafana как код - provisioning источников данных
- Урок 8.7: Логи, Loki и Alloy - JSON-логи и конфиг Alloy, который мы расширяем, кардинальность (число разных значений у лейбла: чем их больше, тем дороже хранение)
- Если хочешь разобрать основы на другом стенде, см. Трейсы в курсе «Мониторинг и SRE».
Картина целиком
Запрос проходит несколько участников: браузер или curl, приложение, база данных. Каждый записывает, когда получил запрос и сколько его обрабатывал. На запросе стоит общий номер (trace_id, он едет в заголовке traceparent), поэтому записи всех участников собираются в одну картину: кто сколько держал запрос и где он застрял. Это тот же маршрутный лист посылки, что в начале урока.
flowchart TD
CL["Клиент (curl)<br>заголовок traceparent с trace_id"] --> APP["notes: приложение с OpenTelemetry SDK<br>спан HTTP GET /notes, внутри него спан db"]
APP -->|"OTLP/HTTP, порт 4318, в фоне"| AL["Alloy (сборщик)<br>принимает OTLP, пакует в батчи"]
AL -->|"OTLP/gRPC, порт 4317 внутри notes-net"| TP["Tempo (хранилище трейсов)<br>порт 3200 для запросов"]
TP -->|"TraceQL и поиск по trace_id"| GR["Grafana: Explore (Tempo)<br>ссылки лог и трейс"]
Схема читается сверху вниз как путь одного запроса. Спаны уходят в сборщик в фоне, поэтому приложение не ждёт хранилище.
Несколько слов с диаграммы. Сборщик (collector) это программа между приложением и хранилищем: принимает спаны пачками и пересылает дальше, чтобы приложение не ждало хранилище. Сэмплирование (sampling) это выбор, какую долю трейсов сохранять. SDK (software development kit) это библиотека внутри приложения, которая создаёт спаны. Всё разберём в теории.
Тот же trace_id приложение пишет в каждую строку JSON-лога (урок 8.7). Поэтому из трейса можно перейти к логам этого запроса, а из строки лога к трейсу. Дальше в теории по порядку: три сигнала, что такое трейс и спан, как контекст передаётся между сервисами, как приложение создаёт спаны, чем OTLP и сборщик помогают, как хранит и ищет Tempo, что такое сэмплирование и как связать три сигнала.
Теория
Три сигнала: метрики, логи, трейсы
Наблюдаемость (observability) держится на трёх видах данных, потому что каждый отвечает на свой вопрос, а один вид не заменяет другие. Без понимания разницы люди либо пытаются лечить всё метриками, либо тонут в логах.
| Сигнал | Отвечает на вопрос | Что хранит | Цена |
|---|---|---|---|
| Метрика (урок 8.2) | сколько и как часто | число во времени | дёшево, агрегаты |
| Лог (урок 8.7) | что случилось | запись о событии | средне, текст |
| Трейс (этот урок) | где в цепочке ушло время | путь одного запроса | дорого, поэтому его часто сэмплируют |
Метрика показывает, что p95 (время, быстрее которого отвечают 95% запросов) вырос до 800 мс. Лог показывает, что запросы завершаются успешно. Трейс показывает, что 700 из этих 800 мс запрос ждал базу.
Разберём на примере. Гистограмма длительности запросов из урока 8.2 и её p95 из урока 8.3 говорят: «p95 для /notes равен 42 мс», то есть 95% запросов быстрее. Это агрегат по тысячам запросов. Чтобы понять, куда уходит время у одного конкретного запроса, нужен трейс: у типичного запроса 42 мс = 11 мс приложение + 31 мс база.
Прикинь сам: какой сигнал ответит на вопрос «какой из трёх сервисов в цепочке даёт задержку»?
Трейс: он показывает длительность каждого шага цепочки. Метрика скажет только, что цепочка стала медленной, лог только что где-то что-то произошло.
Частая ошибка: думать, что трейсы «просто логи с временем». Нет: у трейса есть структура (дерево вложенных шагов) и общий идентификатор, который связывает шаги разных сервисов. Логи каждого сервиса пишутся независимо, склеить их «на глаз» по времени ненадёжно.
Главное: метрика говорит «что и сколько», лог говорит «что случилось», а трейс показывает «в каком месте».
Из чего состоит трейс?
Трейс, спан и контекст
Чтобы увидеть, куда ушло время, запрос надо разложить на шаги и запомнить, кто кого вызвал. Для этого нужны единицы записи и способ их связать.
Вернёмся к посылке: трейс это весь маршрутный лист, а спан одна строка в нём. Склад принял посылку и отдал дальше: это шаг, а внутри шага могут быть свои шаги, например «распаковали» и «проверили».
Спан (span) это одна единица работы с началом, длительностью и атрибутами (пары «ключ=значение» с подробностями): «обработать HTTP GET /notes», «выполнить SELECT». Трейс это дерево спанов одного запроса. У всего трейса один trace_id, у каждого спана свой span_id и ссылка на родителя (parent_span_id). Спан без родителя корневой. Кроме этого у спана есть вид (kind): SERVER для обработки входящего запроса, CLIENT для исходящего вызова, INTERNAL для работы внутри процесса, и статус: OK или ERROR.
Идентификаторы записывают в шестнадцатеричной системе (hex): это способ писать числа цифрами 0-9 и буквами a-f, где один символ несёт четыре бита. trace_id это 128 бит, то есть 32 hex-символа, span_id это 64 бита, то есть 16 символов. Случайное 128-битное число практически не повторится, поэтому никакой центральной выдачи номеров не нужно.
gantt
dateFormat X
axisFormat %L мс
title trace_id 4bf92f35..., корневой и дочерний спаны
section Спаны
HTTP GET /notes (корневой, 42 мс) : 0, 42
db SELECT notes (дочерний, 31 мс) : 6, 37
Дочерний спан начался позже родителя и закончился раньше: он лежит внутри его полосы. Из 42 мс в базу ушло 31 мс.
Разберём на примере. По картинке видно главное: 31 из 42 мс ушло в базу. Остаётся 11 мс на всё остальное: разбор запроса, формирование ответа. Дочерний спан начался позже родителя (пока приложение разбирало запрос) и закончился раньше (пока формировало ответ). Метрика с гистограммой показала бы только общее время, например p95 в 42 мс.
Частая ошибка: trace_id и span_id: первый общий для всего запроса, второй уникален у каждого шага. И ещё: путают спан с процессом или сервисом. Спан это шаг внутри запроса, у одного сервиса за один запрос их может быть несколько.
Главное: трейс это дерево спанов одного запроса, у всех общий
trace_id, а у каждого шага свойspan_id.
Проверь понимание: чем спан отличается от трейса и что у них общего?
Ответ
Трейс это всё дерево запроса, спан это один узел дерева. У всех спанов одного трейса общий trace_id, а span_id у каждого свой. Связь «родитель-потомок» задаёт поле parent_span_id.
Как трейс не рвётся между сервисами?
Пропагация контекста: как трейс не рвётся
Когда сервис A вызывает сервис B, B работает в другом процессе, возможно на другом сервере. Общей памяти у них нет. Чтобы B нарисовал свои спаны как продолжение A, ему надо как-то узнать trace_id. Иначе получатся два несвязанных трейса вместо одного.
Контекст трассировки (trace context) передают в HTTP-заголовке traceparent (стандарт W3C Trace Context; заголовок это строка «имя: значение» в начале HTTP-запроса, урок 2.4). Это называется пропагация (propagation, «передача по цепочке»):
flowchart LR
V["00<br>версия"] --- T["4bf92f3577b34da6a3ce929d0e0e4736<br>trace_id, 32 hex"] --- S["00f067aa0ba902b7<br>span_id родителя, 16 hex"] --- F["01<br>флаги: сохранять"]
Заголовок состоит из четырёх частей через дефис: версия, номер трейса, номер родительского шага и флаги.
Порядок действий такой. Клиент или сервис A создаёт спан и кладёт его span_id в traceparent исходящего запроса. Сервис B на входе читает заголовок (это называется extract, «извлечь»), берёт оттуда trace_id и делает свой спан дочерним к span_id из заголовка. Если B вызывает дальше, он кладёт в исходящий заголовок уже свой span_id (inject, «вложить»).
Разберём на примере. Клиент отправил запрос с traceparent: 00-4bf9...4736-00f067aa0ba902b7-01. Приложение создаёт серверный спан с trace_id = 4bf9...4736 и родителем 00f067aa0ba902b7. Затем создаёт спан базы: trace_id тот же, родитель уже серверный спан приложения. В Tempo все три записи окажутся в одном трейсе. Если бы заголовка не было, приложение сгенерировало бы новый trace_id.
Прикинь сам: запрос пришёл в nginx, потом в приложение. В Tempo два трейса вместо одного. Что подозреваешь?
Где-то потерян заголовок traceparent: nginx не проксирует его (или клиент не отправил), приложение стартует новый корневой спан. Проверять: что показывает /headers (эндпоинт приложения из урока 2.4 возвращает заголовки, дошедшие до него) и пробрасывает ли прокси заголовки.
Частая ошибка: думать, что трейс «сам» связывается. Связывает только заголовок, и если хоть один участник цепочки его потерял (прокси срезал, клиент не добавил, приложение не вызвало extract), в Tempo вместо одного трейса окажутся два несвязанных огрызка. Это самая частая поломка трейсинга.
Главное: контекст передаётся заголовком
traceparent, и без него следующее звено заведёт новый трейс.
Кто создаёт спаны?
Как приложение создаёт спаны: SDK, инструментирование, экспорт
Спаны не появляются сами: кто-то должен в коде сказать «здесь начался шаг, здесь закончился» и отправить запись наружу. Для этого есть библиотека, готовая для всех языков.
OpenTelemetry (OTel) это стандарт CNCF (фонд, под которым живут Prometheus, Kubernetes и другие) для телеметрии: API и SDK в коде приложения, формат данных и протокол. Приложение использует три части. API (opentelemetry-api) это интерфейс «начать спан, задать атрибут». SDK (opentelemetry-sdk) реализует его: создаёт идентификаторы, копит спаны. Экспортёр (opentelemetry-exporter-otlp-proto-http) отправляет их по сети. Инструментирование (instrumentation) это создание спанов: автоматически библиотеками для популярных фреймворков или вручную. Мы делаем вручную, чтобы видеть, что происходит: в обработчике запроса одна конструкция with tracer.start_as_current_span(...).
Экспорт идёт в фоне. BatchSpanProcessor складывает завершённые спаны в очередь и отправляет пачками отдельным потоком. Отсюда два свойства. Приложение не тормозит из-за трейсинга: отправка не в цепочке запроса. Приложение не падает, если сборщик недоступен: ошибка экспорта попадает в лог, а очередь конечна, поэтому при долгой недоступности часть спанов теряется. Это плата за то, что трейсы не должны мешать основной работе.
Разберём на примере. Обработчик GET /notes: входим в серверный спан (в него попадает вся обработка), внутри вызываем list_notes(), где обёрнут в спан db запрос в PostgreSQL. По выходе из блока спаны закрываются и уходят в очередь. Если OTEL_EXPORTER_OTLP_ENDPOINT не задан, приложение работает без трейсинга: функция setup_tracing() возвращает None, и спанов не создаётся.
Частая ошибка: думать, что «включить трейсинг» значит поставить пакет. Пакет ничего не делает, пока в коде не созданы спаны и не задан адрес экспорта. Ещё путают имя спана и его атрибуты: в имени не должно быть уникальных значений (следующий раздел про Tempo объясняет почему: и в трейсинге действует кардинальность).
Главное: SDK создаёт спаны, а экспорт идёт в фоне пачками, поэтому трейсинг не тормозит запросы.
Проверь понимание: сборщик недоступен минуту. Что случится с приложением и со спанами этой минуты?
Ответ
Приложение продолжит работать: экспорт идёт в фоне, ошибки попадут в лог. Спаны копятся в очереди ограниченного размера; при переполнении новые или старые теряются. Накопленное в очереди уйдёт, когда сборщик вернётся.
Куда спаны уходят?
OTLP и сборщик: между приложением и хранилищем
Приложение не должно знать, где хранятся трейсы. Сегодня Jaeger, завтра Tempo, послезавтра облачный сервис: если адрес хранилища вшит в код, каждая смена требует пересборки.
OTLP (OpenTelemetry Protocol) это единый формат и способ передачи телеметрии. Приложение шлёт OTLP на адрес из переменной окружения OTEL_EXPORTER_OTLP_ENDPOINT (переменная окружения это именованное значение, которое задаётся при запуске процесса). Сменить хранилище можно без правки кода.
OTLP ходит по двум транспортам, и порт выбирает транспорт:
| Порт | Транспорт | Как устроен | Кто у нас им пользуется |
|---|---|---|---|
| 4318 | HTTP | обычный запрос, путь /v1/traces, тело это упакованные спаны |
приложение шлёт в Alloy |
| 4317 | gRPC | способ вызвать функцию по сети: компактные двоичные данные (байты, а не читаемый текст) по одному постоянному соединению | Alloy шлёт в Tempo |
HTTP ты уже знаешь из урока 2.4. gRPC экономнее по трафику, зато сложнее отлаживать: curl с текстом его не поймёт. Приёмник (у нас Alloy) слушает оба порта одновременно, а клиент использует один из них. Транспорты не взаимозаменяемы: клиент, говорящий по HTTP, на порт 4317 попадёт как в стену, ошибка будет запутанной (connection reset, unexpected EOF). Порт открыт не значит, что протокол совпал. Проверка за минуту: порт 4318 отвечает на обычный HTTP-запрос, порт 4317 нет. Поэтому первым делом при «трейсов нет» сверяй пару «протокол и порт».
Между приложением и хранилищем ставят сборщик (collector). У нас его роль играет Grafana Alloy, который ты уже настроил в уроке 8.7 для логов: он принимает OTLP, пакует спаны в батчи (пачки) и отправляет в Tempo.
flowchart LR
A["notes<br>SDK, OTLP/HTTP"] --> B["Alloy :4318"] --> C["Tempo<br>OTLP/gRPC :4317 внутри сети"] --> D["Grafana :3000"]
Разберём на примере. Путь одного спана: приложение завершило спан db, BatchSpanProcessor положил его в очередь, через секунды пачка ушла POST-запросом на http://alloy:4318/v1/traces. Alloy принял (otelcol.receiver.otlp), собрал в батч (otelcol.processor.batch) и передал (otelcol.exporter.otlp) в Tempo на tempo:4317. Слова в названиях компонентов читаются как роли: receiver принимает, processor обрабатывает, exporter отправляет.
Прикинь сам: зачем между приложением и Tempo нужен сборщик, если приложение может слать в Tempo напрямую?
Сборщик буферизует и батчит данные, переживает кратковременную недоступность хранилища, может добавлять атрибуты, отбрасывать лишнее и сэмплировать. Приложение при этом знает один стабильный адрес и не зависит от того, какое хранилище стоит за ним.
Главное: OTLP это единый протокол с двумя транспортами (см. таблицу выше), клиент и порт должны говорить на одном языке.
Где спаны хранятся?
Tempo и TraceQL: хранение и поиск
Трейсов много: у сервиса на 100 запросов в секунду за сутки набегает около 8,6 миллиона трейсов. Нужно хранилище, которое принимает поток, хранит недорого и умеет искать нужное.
Grafana Tempo хранит трейсы блоками на диске или в объектном хранилище и не строит индекс по всем атрибутам, поэтому дёшев. Свежие спаны сначала лежат в памяти и журнале записи (WAL, write-ahead log), потом сбрасываются в блоки на диск. Отсюда задержка: только что отправленный трейс может быть найден не сразу, подожди несколько секунд. Срок хранения задаёт компактор (block_retention), как retention в Loki из урока 8.7.
Ищут либо по trace_id (мгновенно, если он известен), либо запросом на языке TraceQL. Запрос перебирает блоки в заданном интервале:
{ resource.service.name = "notes" && duration > 500ms }
{ span.http.response.status_code >= 500 }
Разбор: в фигурных скобках условие на спан; resource.service.name атрибут ресурса (того, что породило спан: имя сервиса), span.http.response.status_code атрибут самого спана, duration длительность; && значит «и».
Разберём на примере. Запрос { resource.service.name = "notes" && duration > 900ms } вернёт трейсы, у которых есть спан сервиса notes длиннее 900 мс. Если запрос к /slowsql?sec=1 ждёт pg_sleep(1) в базе, спан HTTP GET /slowsql попадёт в выборку, а обычные быстрые запросы нет. Из найденного трейса видно структуру: где именно ушла секунда.
Частая ошибка: думать, что Tempo быстро ищет по любому атрибуту, как поисковик. Быстро только по trace_id; остальное это сканирование в пределах интервала, поэтому запросы стоит ограничивать по времени. Ещё путают имя спана с атрибутом: имя должно быть шаблоном (HTTP GET /notes), а настоящий адрес (/notes/123) кладут в атрибут. Иначе у трейсов миллионы разных имён и поиск по ним бесполезен, как лейбл path в Loki.
Главное: Tempo не индексирует все атрибуты, поэтому по
trace_idищет мгновенно, а TraceQL перебирает блоки.
Проверь понимание: ты знаешь
trace_idи хочешь найти трейс. Как быстрее всего?
Ответ
Запросить по идентификатору: GET /api/v2/traces/<trace_id> или поиск по ID в Explore. Это единственный поиск, который Tempo выполняет мгновенно без сканирования блоков.
Сколько трейсов хранить?
Сэмплирование: сколько трейсов хранить
Хранить трейс каждого запроса при большой нагрузке дорого. Обычно интересны ошибки и медленные запросы, а миллионы одинаковых быстрых успешных запросов мало что добавляют.
Сэмплирование (sampling) это выбор, какие трейсы сохранить. Head-сэмплирование решает в начале запроса, до выполнения («сохраняем 10%»): просто и дёшево, но решение принимается вслепую. Tail-сэмплирование решает после завершения трейса («сохраняем все ошибки, все медленные и 5% остальных»): видит результат, но сборщику приходится держать спаны в буфере до конца трейса. Флаг 01 в конце traceparent как раз говорит «этот трейс сохраняется».
Для tail-сэмплирования в Alloy есть компонент otelcol.processor.tail_sampling. Набросок политик (в стенде не запускался, имена блоков сверь с документацией своей версии Alloy):
otelcol.processor.tail_sampling "default" {
decision_wait = "10s" // сколько ждать конца трейса перед решением
policy {
name = "errors"
type = "status_code"
status_code { status_codes = ["ERROR"] }
}
policy {
name = "slow"
type = "latency"
latency { threshold_ms = 500 }
}
policy {
name = "rest"
type = "probabilistic"
probabilistic { sampling_percentage = 5 }
}
output { traces = [otelcol.processor.batch.default.input] }
}
Трейс сохраняется, если подошла хотя бы одна политика: ошибка, медленный или попал в 5% остальных. В курсе сэмплирование не включаем: нагрузка мала, сохраняем всё.
Разберём на примере. Сервис даёт 1000 запросов в секунду, из них 1% ошибок. Head 10% сохранит 100 трейсов в секунду, из которых ошибочных около одного: из 10 ошибок в секунду 9 потеряны. Tail (все ошибки и 5% остальных, как в наброске выше) сохранит 10 ошибок и около 50 обычных в секунду (5% от 990): 60 трейсов вместо 100, и все ошибки на месте.
Объём пропорционален доле сохранённых трейсов, поэтому сэмплирование это главный способ управлять ценой.
Прикинь сам: почему для поиска причин инцидента tail-сэмплирование полезнее head?
Head принимает решение до того, как известно, будет ли запрос ошибочным или медленным, и выбросит часть как раз интересных трейсов. Tail видит результат целиком и оставляет все аномальные, а из нормальных берёт небольшую долю.
Частая ошибка: думать, что сэмплирование «портит» картину. Метрики считаются по всем запросам независимо от сэмплирования, они остаются точными. Сэмплирование относится только к трейсам.
Главное: head-сэмплирование решает до выполнения, tail после, а в курсе хранится всё, потому что нагрузка мала.
Как читать результат?
Как читать трейс: диаграмма-водопад
Tempo и Grafana показывают трейс как диаграмму, и умение читать её с одного взгляда экономит минуты в каждом инциденте. Новичок видит набор цветных полос, опытный человек видит ответ.
Каждая строка это спан. Слева имя, полоса показывает, когда он начался и как долго шёл на общей оси времени. Вложенные спаны отступают вправо и лежат внутри полосы родителя. Читай по порядку. Первое: длина корневой полосы, это общее время запроса. Второе: какая из вложенных полос самая длинная, это главный подозреваемый. Третье: есть ли «дыры», то есть отрезки, где у родителя есть время, а у потомков нет: там работает сам родитель (или ждёт что-то, что не оформлено спаном). Четвёртое: последовательные или параллельные полосы: если пять запросов идут по очереди, а могли бы одновременно, это находка. Пятое: спаны со статусом ERROR подсвечены, у них в атрибутах причина.
Разберём на примере. Трейс HTTP GET /slowsql?sec=1: корневая полоса 1010 мс, внутри спан db на 1000 мс (это pg_sleep(1) в базе). Дыра в 10 мс это разбор запроса и формирование ответа. Вывод: 99% времени ушло в базу, оптимизировать приложение бессмысленно. Метрика по гистограмме показала бы только «запрос длился секунду».
Найди строку с самым большим собственным временем: у корня оно включает всех потомков, поэтому самая длинная полоса не обязательно виновница.
Частая ошибка: думать, что самая длинная полоса всегда виновница. Корень всегда самый длинный, он включает всех потомков. Смотреть надо на «собственное время» спана: его длительность минус длительность его детей. У корня из примера это 10 мс, у db 1000 мс.
Главное: вина лежит на спане с большим собственным временем, а не на самой длинной полосе, потому что корень включает всех потомков.
Проверь понимание: корневой спан 500 мс, у него два дочерних подряд по 200 мс. Где ушли остальные 100 мс?
Ответ
В собственное время родителя: 500 - 200 - 200 = 100 мс. Это работа самого приложения между вызовами (или ожидание, которое не обёрнуто спаном).
Чем описать спан?
Атрибуты и ресурс: чем описать спан
Одной длительности мало. Чтобы искать «пятисотые» и «только сервис notes» или «только метод POST», у спана должны быть поля, по которым запрос TraceQL их отберёт.
Ярлык на посылке: отправитель (кто) и содержимое, вес, срочность (что именно). Ярлык отправителя один на всю партию, содержимое у каждой посылки своё.
Данные о том, кто породил спан, называются ресурсом (resource): имя сервиса service.name, версия, узел. Ресурс один на приложение и прикрепляется ко всем его спанам. Данные о конкретном шаге называются атрибутами спана (span attributes): http.request.method, http.response.status_code. В TraceQL их различают префиксами resource. и span.. В OpenTelemetry есть соглашения об именах (semantic conventions), например http.response.status_code, чтобы разные программы называли одно и то же одинаково, и запросы работали у всех.
Разберём на примере. Наш request_span ставит атрибуты http.request.method и http.response.status_code, а если код 500 или больше, статус спана ERROR. Ресурс создаётся один раз в setup_tracing() и содержит service.name = "notes" из переменной OTEL_SERVICE_NAME. Поэтому запрос { resource.service.name = "notes" && span.http.response.status_code >= 500 } найдёт ошибочные запросы именно этого сервиса.
Прикинь сам: в Tempo сервис назван
unknown_service:python. Что забыли?
Задать имя сервиса: service.name в ресурсе (через OTEL_SERVICE_NAME или в коде). Без него SDK подставляет имя по умолчанию.
Частая ошибка: Имя сервиса и имя спана. Имя сервиса лежит в ресурсе (notes), имя спана описывает шаг (HTTP GET /notes). Ещё путают атрибуты с лейблами Loki: атрибуты не индексируются по одному, их значения можно делать высококардинальными (user.id), но не бесконтрольно: каждый атрибут занимает место в хранилище.
Главное: ресурс описывает «кто» и один на приложение, а атрибуты описывают конкретный шаг.
Что делать, если трейсов нет?
Трейсов нет: как искать обрыв по участкам
Самая частая история с трейсингом: «включили, а в Tempo пусто». Причин десяток, и без плана диагноз превращается в гадание. План простой: цепочка из четырёх звеньев, и проверяем каждое отдельно.
Звенья: приложение (создаёт и экспортирует спаны), сеть и порт (доходит ли до Alloy), Alloy (принимает и передаёт в Tempo), Tempo (хранит и отдаёт). Проверка идёт от источника: включён ли экспорт (OTEL_EXPORTER_OTLP_ENDPOINT не пуст), что пишет экспортёр в лог приложения (ошибки соединения, коды ответа), отвечает ли приёмник на спан, посланный вручную (задание 2), что пишет Alloy при отправке в Tempo, готов ли Tempo (/ready) и находится ли трейс по trace_id после паузы. Ручной спан из задания 2 сразу делит цепочку пополам: если он дошёл, сломано между приложением и Alloy, если нет, между Alloy и Tempo.
Разберём на примере. Трейсов нет. В логе приложения: Failed to export batch ... Connection reset by peer (или unexpected EOF). Значит, звено «приложение - Alloy» сломано: порт отвечает, но не тем протоколом. Проверяем адрес: http://alloy:4317, порт gRPC, а экспортёр HTTP, ему нужен 4318. Исправили адрес, перезапустили приложение, трейсы пошли.
Частая ошибка: думать, что «нет ошибок» значит «всё хорошо». Экспорт в фоне может тихо терять спаны. Ещё путают «трейса нет» с «трейс не успел»: между отправкой и появлением в Tempo проходят секунды.
Главное: обрыв ищут по участкам от источника: приложение, сеть и порт, Alloy, Tempo.
Проверь понимание: ручной спан из задания 2 дошёл до Tempo, а спаны приложения нет. Какое звено подозреваешь?
Ответ
Звено «приложение - Alloy»: сам Alloy и Tempo работают (ручной спан прошёл), значит проблема в адресе, порту или протоколе экспорта в приложении, либо в том, что трейсинг не включён (пустой OTEL_EXPORTER_OTLP_ENDPOINT).
Ошибки в трейсе: статус спана
Трейс нужен не только для медленных запросов. Запрос может упасть, и важно сразу увидеть, на каком шаге. Без пометки об ошибке пришлось бы открывать каждый трейс и читать атрибуты.
У каждого спана есть статус: UNSET (по умолчанию: ничего не сказано), OK или ERROR. Спан со статусом ERROR Grafana подсвечивает красным. Статус ставит приложение: у нас request_span помечает спан ошибкой, если код ответа 500 или больше. Тогда в TraceQL можно искать не по числу, а по статусу: { status = error }, все спаны с ошибкой. Важное свойство: ошибка одного спана не делает ошибочным весь трейс автоматически. Если db упал, а приложение поймало ошибку и вернуло 200, корень будет без ошибки, а db красным.
Разберём на примере. Запрос /error у «Заметок» отвечает кодом 500. Трейс: корневой спан HTTP GET /error со статусом ERROR и атрибутом http.response.status_code=500. В логе того же запроса лежит тот же trace_id. Идёшь из трейса в лог и читаешь текст ошибки. Если бы статус не ставился, такой трейс ничем не отличался бы от обычного, и его пришлось бы искать по коду в атрибутах.
Частая ошибка: думать, что красный спан это всегда авария. Иногда ошибка ожидаема (например, «заметка не найдена» при проверке несуществующего id), и тогда это нормальная работа. Ещё путают статус спана и HTTP-код: код это данные об ответе, статус это оценка «плохо или нет», которую ставит программа.
Главное: статус
ERRORставит приложение, и по нему отбирают проблемные трейсы без чтения остальных.
Проверь понимание: спан
dbпомеченERROR, корневой спан нет, клиент получил 200. Как это объяснить?
Ответ
Приложение поймало ошибку базы и обработало её (например, вернуло данные из запасного источника). Статус спана показывает состояние конкретного шага, а не всего запроса: на db была ошибка, на уровне приложения она скрыта от клиента.
Сколько это стоит?
Сколько стоит трейсинг: объём и накладные расходы
Трейсинг не бесплатный: каждый спан занимает место и немного процессорного времени. Если включить его без расчёта, хранилище заполнится, а сервис станет чуть медленнее. Нужно уметь оценить цену заранее.
Цена складывается из трёх частей. Первая: память и процессор приложения на создание спана (обычно микросекунды на спан, поэтому для типичных сервисов заметной разницы нет). Вторая: сеть, отправка пачками по OTLP. Третья: хранение в Tempo, оно растёт с числом спанов. Число спанов на запрос зависит от того, сколько шагов ты обернул: у «Заметок» это два-три (HTTP, база), у большого сервиса может быть сто. Снижают цену тремя способами: меньше лишних спанов, сэмплирование (см. раздел выше) и короткий срок хранения.
Разберём на примере. Сервис получает 100 запросов в секунду, на каждый по 3 спана, каждый спан занимает около 500 байт. 100 × 3 × 500 = 150 000 байт в секунду, за сутки 150 000 × 86 400 = 12,96 миллиарда байт, около 13 ГБ. Если сохранять 10% (head-сэмплирование), выйдет около 1,3 ГБ в сутки. При хранении 7 дней это 9 ГБ вместо 91 ГБ. Для лаборатории с малой нагрузкой это пустяк, для боевого сервиса разница в деньгах.
Прикинь сам: сервис даёт 10 запросов в секунду, по 4 спана по 500 байт. Сколько это в сутки без сэмплирования?
10 × 4 × 500 = 20 000 байт в секунду. 20 000 × 86 400 = 1,728 миллиарда байт, около 1,7 ГБ в сутки.
Частая ошибка: думать, что трейсинг «тормозит приложение». При разумном числе спанов накладные расходы малы, а основной счёт приходит за хранение, а не за процессор. Второе: что можно отключить трейсинг, когда всё хорошо. Трейс нужен именно до аварии: задним числом его не воссоздать.
Главное: объём считается как запросы в секунду на число спанов и размер спана, а сэмплирование снижает его пропорционально.
Как связать с логами?
Связь трёх сигналов: trace_id в логах
Три сигнала полезны по отдельности, но настоящая скорость приходит, когда от одного можно перейти к другому одним щелчком: от графика к трейсу, от трейса к логам этого запроса.
Приложение пишет trace_id текущего спана в каждую строку JSON-лога (урок 8.7). В Grafana настраивают ссылки в обе стороны. Из Loki: производное поле (derived field) вытаскивает регулярным выражением trace_id из строки и делает ссылку на Tempo. Из Tempo: tracesToLogsV2 открывает Loki с запросом по этому trace_id. Для метрик применяют exemplars: к точке гистограммы прикрепляют trace_id конкретного запроса, попавшего в эту корзину.
Связывает именно идентификатор, а не время. По времени в одну секунду могут попасть сотни запросов, и выбрать нужный не получится. Но trace_id нельзя делать лейблом Loki или Prometheus: значений миллионы (кардинальность из урока 8.7). Он остаётся полем в теле записи, и ищут его фильтром | json | trace_id="...".
Разберём на примере. Ты нашёл в Tempo медленный трейс, trace_id=4bf9...4736. Нажимаешь «Logs for this span», и Grafana открывает Loki с запросом {service="notes"} | json | trace_id="4bf9...4736". Видишь одну запись: "path":"/slowsql","dur_ms":1003. Теперь и время, и причина, и запись лога у тебя перед глазами.
Частая ошибка: думать, что для связи достаточно «смотреть в то же время». Не достаточно, нужен общий идентификатор. И ещё, из практики безопасности: в атрибуты спанов и в логи нельзя класть почты, токены и тела запросов. Телеметрия хранится долго и читается многими, а тяжёлые атрибуты раздувают хранилище.
Главное:
trace_idв каждой строке лога связывает три сигнала, но лейблом он быть не может из-за кардинальности.
Проверь понимание: почему
trace_idв Loki не лейбл, а поле, хотя по нему ищут?
Ответ
У каждого запроса свой trace_id, значит миллионы уникальных значений. Как лейбл он создал бы поток на каждый запрос и раздул индекс. Как поле он не индексируется, а находится фильтром по тексту в потоках сервиса, что дёшево и достаточно быстро.
Практика
Все команды выполняются из ~/notes. Основной compose.yml и стек monitoring/ из урока 8.7 должны работать (Loki, Alloy, Grafana). Нужны curl, jq и openssl.
Если у тебя 8 ГБ
Останови то, что в этом уроке не нужно:
docker compose -f monitoring/compose.yml stop cadvisor node_exporter blackbox alertmanager
docker stats --no-stream
docker stats --no-stream один раз печатает, сколько процессора и памяти используют контейнеры. Если памяти всё равно мало, останови ещё и Prometheus: он понадобится в 8.9.
Задание 1. Tempo и приём OTLP в Alloy
Цель: запустить Tempo и научить Alloy принимать OTLP и отправлять спаны в Tempo.
Предскажи: какие из портов 3200, 4317, 4318 будут опубликованы на хосте? Подумай, кто с кем разговаривает.
Ответ
Наружу нужны 3200 (Tempo API, к нему ходит ты с хоста; Grafana ходит внутри сети) и 4317/4318 (принимает Alloy: с хоста удобно слать тестовые спаны). Tempo слушает OTLP на 4317 только внутри сети notes-net, публиковать его на хосте нельзя: порт 4317 уже занят Alloy.
Шаги:
- Создай
monitoring/tempo/tempo.yml:
# Tempo в одиночном режиме: хранение на локальном диске, всё в одном процессе
server:
http_listen_port: 3200 # API запросов: /ready, /api/v2/traces/<id>
distributor: # приёмная часть: принимает спаны
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317 # сюда шлёт Alloy
http:
endpoint: 0.0.0.0:4318
ingester:
max_block_duration: 2m # закрываем блок быстро, чтобы свежие трейсы находились поиском
storage:
trace:
backend: local # блоки на диске, без объектного хранилища
wal:
path: /var/tempo/wal # журнал свежих спанов до сброса на диск
local:
path: /var/tempo/blocks
# хранить трейсы 24 часа: для учебного стенда достаточно
compactor:
compaction:
block_retention: 24h
- Добавь в
monitoring/compose.ymlсервисtempoи томtempo-data(остальные сервисы не трогай):
tempo:
image: grafana/tempo:2.10.8
command: ["-config.file=/etc/tempo/tempo.yml"]
ports:
- "127.0.0.1:3200:3200" # только с этого хоста
volumes:
- ./tempo/tempo.yml:/etc/tempo/tempo.yml:ro
- tempo-data:/var/tempo
restart: unless-stopped
В секции volumes: в конце файла добавь tempo-data:. В сервисе alloy опубликуй порты "127.0.0.1:4317:4317" и "127.0.0.1:4318:4318" (рядом с уже опубликованным 12345).
- Добавь в конец
monitoring/alloy/config.alloy(блоки логов из урока 8.7 оставь как есть):
// приём OTLP от приложений: gRPC на 4317 и HTTP на 4318
otelcol.receiver.otlp "default" {
grpc {
endpoint = "0.0.0.0:4317"
}
http {
endpoint = "0.0.0.0:4318"
}
output {
traces = [otelcol.processor.batch.default.input]
}
}
// батчи уменьшают число запросов к Tempo
otelcol.processor.batch "default" {
output {
traces = [otelcol.exporter.otlp.tempo.input]
}
}
// отправка в Tempo по gRPC внутри сети, без TLS (только для лаборатории)
otelcol.exporter.otlp "tempo" {
client {
endpoint = "tempo:4317"
tls {
insecure = true
}
}
}
Разбор. Три компонента образуют цепочку так же, как в уроке 8.7: приёмник receiver отдаёт трейсы (traces) на вход processor, тот на вход exporter. Приёмнику указаны 0.0.0.0 (слушать на всех адресах контейнера, иначе сообщение от другого контейнера не пройдёт) и оба транспорта. TLS (шифрование канала) выключен только потому, что трафик не выходит за пределы docker-сети.
- Примени и проверь готовность:
docker compose -f monitoring/compose.yml up -d tempo alloy
sleep 20
curl -s http://localhost:3200/ready
Разбор. -f monitoring/compose.yml указывает файл Compose, up -d tempo alloy создаёт или пересоздаёт только эти два сервиса. Пауза sleep 20 нужна, чтобы Tempo успел запуститься. /ready проба готовности.
Что должно получиться:
ready
Как читать вывод: слово ready значит, что Tempo принимает запросы. Если сразу пришло Ingester not ready: waiting for 15s after being ready, Tempo ещё прогревается: подожди ещё 15 секунд и повтори.
Объясни себе:
- Почему Alloy шлёт в Tempo по gRPC, хотя приложение будет слать в Alloy по HTTP?
Типичные ошибки:
Error response from daemon: driver failed programming external connectivity ... Bind for 0.0.0.0:4317 failed: port is already allocated: порт 4317 опубликован у двух сервисов. Убери публикацию 4317 уtempo, оставь уalloy.failed to load config: ... field distributor not foundв логе Tempo: опечатка или неверный отступ вtempo.yml. Проверьdocker compose -f monitoring/compose.yml logs tempo.
Задание 2. Отправь трейс вручную
Цель: увидеть, что OTLP это обычный HTTP с JSON, и пройти путь спана от Alloy до Tempo без приложения.
Предскажи: если отправить один спан на http://localhost:4318/v1/traces, какой HTTP-код вернёт Alloy: 200, 202 или 204? И сразу ли спан появится в Tempo?
Ответ
Ответ OTLP/HTTP при успехе: 200 с телом {"partialSuccess":{}}. В Tempo спан появится не сразу: сначала он в памяти (ingest), поэтому запрос по trace_id может вернуть 404 в течение нескольких секунд.
Шаги:
# идентификаторы: trace_id 32 hex, span_id 16 hex
TRACE_ID=$(openssl rand -hex 16)
SPAN_ID=$(openssl rand -hex 8)
START=$(date +%s%N)
END=$((START + 250000000)) # спан длится 250 мс
curl -s -o /dev/null -w 'HTTP %{http_code}\n' \
-H 'Content-Type: application/json' \
-d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"manual-test"}}]},
"scopeSpans":[{"spans":[{"traceId":"'$TRACE_ID'","spanId":"'$SPAN_ID'","name":"hello","kind":1,
"startTimeUnixNano":"'$START'","endTimeUnixNano":"'$END'"}]}]}]}' \
http://localhost:4318/v1/traces
echo "trace_id=$TRACE_ID"
sleep 10
curl -s http://localhost:3200/api/v2/traces/$TRACE_ID | jq -r '.trace.resourceSpans[].scopeSpans[].spans[].name'
Разбор по кускам. openssl rand -hex 16 выдаёт 16 случайных байт в виде 32 hex-символов (это trace_id), -hex 8 даёт 16 символов (span_id). date +%s%N печатает текущее время в наносекундах с 1 января 1970 года: OTLP хранит время именно так (N работает в GNU date на Ubuntu, на macOS не работает). $((START + 250000000)) арифметика в оболочке: 250 000 000 наносекунд это 250 мс. В curl флаг -w 'HTTP %{http_code}\n' печатает после ответа код ответа, -o /dev/null выбрасывает тело, -H задаёт заголовок, -d тело запроса. Тело это JSON: ресурс с именем сервиса manual-test и один спан с именем hello, идентификаторами и временем начала и конца. Последняя команда просит у Tempo трейс по идентификатору, а jq -r достаёт из ответа имена спанов.
Что должно получиться:
HTTP 200
trace_id=<32 hex-символа>
hello
Как читать вывод: HTTP 200 значит, что Alloy принял спан. Строка hello в конце значит, что спан прошёл весь путь и лежит в Tempo. Если последняя строка пустая, спан ещё в пути или потерялся по дороге: повтори последнюю команду через 10 секунд.
Объясни себе:
- Из каких трёх идентификаторов и временных полей состоит минимальный спан?
Типичные ошибки:
HTTP 000иcurl: (7) Failed to connect to localhost port 4318: Alloy не запущен или порт не опубликован. Проверьdocker compose -f monitoring/compose.yml ps.- Пустой вывод последней команды или
trace not found: спан ещё не дошёл, подожди 10 секунд и повтори запрос.
Задание 3. Приложение v7: трейсы и trace_id в логах
Код отправки трейсов возьми из образца. Проследи, где начинается и заканчивается span, как задаётся адрес приёмника и откуда trace_id попадает в лог. Результат проверь одним запросом к приложению и переходом между его логом и трейсом; самостоятельно реализовывать протокол отправки трейсов не требуется.
Цель: подключить OpenTelemetry SDK к «Заметкам» и увидеть, как один запрос порождает серверный и БД-спан.
Предскажи: приложение получило заголовок traceparent: 00-<trace_id>-<span_id>-01. Какой trace_id будет у его серверного спана: новый или тот же?
Ответ
Тот же. SDK читает traceparent, берёт trace_id из него и делает свой спан дочерним к span_id из заголовка. Именно так трейс продолжается через границу сервисов.
Шаги:
- Добавь в
requirements.txtтри пакета с закреплёнными версиями (актуальные значения лежат в эталонном requirements.txt):
opentelemetry-api==1.45.2
opentelemetry-sdk==1.45.2
opentelemetry-exporter-otlp-proto-http==1.45.2
- В
app.pyдобавь трейсинг. Полный файл: эталон v7. Вот четыре изменения. Первое, импорты и настройка. Если адрес экспорта не задан, трейсинг выключен:
from contextlib import contextmanager
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
def setup_tracing():
"""Включает трейсинг, только если задан OTEL_EXPORTER_OTLP_ENDPOINT."""
endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
if not endpoint:
return None
resource = Resource.create({"service.name": os.environ.get("OTEL_SERVICE_NAME", "notes")})
provider = TracerProvider(resource=resource)
# OTLP/HTTP: путь /v1/traces дописывается к адресу
provider.add_span_processor(BatchSpanProcessor(
OTLPSpanExporter(endpoint=endpoint.rstrip("/") + "/v1/traces")))
trace.set_tracer_provider(provider)
return trace.get_tracer("notes")
PROPAGATOR = TraceContextTextMapPropagator()
tracer = setup_tracing()
Второе, серверный спан на каждый запрос. Он читает traceparent (extract) и продолжает чужой трейс:
@contextmanager
def request_span(handler):
if tracer is None:
yield
return
# имена HTTP-заголовков нечувствительны к регистру
ctx = PROPAGATOR.extract(carrier={k.lower(): v for k, v in handler.headers.items()})
path = route_label(urlparse(handler.path).path) # шаблон пути, а не настоящий URL
with tracer.start_as_current_span(
f"HTTP {handler.command} {path}", context=ctx, kind=trace.SpanKind.SERVER) as span:
span.set_attribute("http.request.method", handler.command)
try:
yield
finally:
status = handler._status or 500
span.set_attribute("http.response.status_code", status)
if status >= 500:
span.set_status(trace.StatusCode.ERROR)
Обработчик запроса оборачивается в него: with request_span(self): ... вокруг self._dispatch() и _access_log. Функция route_label уже есть в v6 (урок 8.2, шаблон пути для метрик).
Третье, спан на каждое обращение к базе. Все функции, которые ходят в PostgreSQL, оборачиваются в with db_span()::
@contextmanager
def db_span():
# Без серверного спана (например, при старте) отдельный трейс БД не нужен.
if tracer is None or not trace.get_current_span().get_span_context().is_valid:
yield
return
with tracer.start_as_current_span("db"):
yield
Четвёртое, trace_id в записи лога. В JsonFormatter.format после entry = {...} и до entry.update(...):
# Лог пишется внутри активного спана: его trace_id связывает лог и трейс.
span_ctx = trace.get_current_span().get_span_context()
if span_ctx.is_valid:
entry["trace_id"] = format(span_ctx.trace_id, "032x")
format(x, "032x") записывает число в hex и дополняет нулями слева до 32 символов.
И последнее: как всё это подключается. Обработчик запроса вызывает request_span, а при остановке приложение отправляет хвост очереди спанов:
def _handle(self):
started = time.monotonic()
self._status = None
with request_span(self): # серверный спан вокруг всей обработки запроса
try:
self._dispatch()
finally:
if self._status is not None:
self._access_log(self._status, started)
# в конце main(), после server.serve_forever() и server.server_close():
if tracer is not None:
trace.get_tracer_provider().shutdown() # отправить оставшиеся спаны из очереди
do_GET у нас просто вызывает _handle. Целиком файл смотри в эталоне v7.
- Добавь в основной
compose.ymlсервисуnotesпеременные окружения (приложение и Alloy в одной сетиnotes-net, адрес по имени сервиса):
environment:
OTEL_EXPORTER_OTLP_ENDPOINT: "http://alloy:4318"
OTEL_SERVICE_NAME: "notes"
Если блок environment: у сервиса уже есть, добавь эти две строки в него.
- Пересобери и запусти, сделай запросы с явным
traceparent:
docker compose up -d --build notes
TP_TRACE=$(openssl rand -hex 16)
curl -sk -H "traceparent: 00-${TP_TRACE}-00f067aa0ba902b7-01" \
-X POST -d '{"text":"проверка трейсинга"}' https://notes.lab/notes
curl -sk -H "traceparent: 00-${TP_TRACE}-00f067aa0ba902b7-01" https://notes.lab/notes > /dev/null
sleep 10
# в логе приложения тот же trace_id, что мы передали
docker compose logs notes | grep "$TP_TRACE" | head -2
# и в Tempo два серверных спана и БД-спаны внутри одного трейса
curl -s http://localhost:3200/api/v2/traces/$TP_TRACE | jq -r '.trace.resourceSpans[].scopeSpans[].spans[].name' | sort | uniq -c
Разбор. --build пересобирает образ перед запуском. traceparent: 00-<trace_id>-<span_id>-01 собран руками из нашего случайного trace_id и любого 16-символьного span_id. grep "$TP_TRACE" оставляет строки лога с этим идентификатором, head -2 первые две. В конце jq достаёт имена спанов, sort | uniq -c группирует одинаковые и считает.
Что должно получиться (значения времени и длительностей у тебя будут другие):
notes-1 | {"ts":"2026-09-29T10:00:00.111+00:00","level":"info","msg":"request","trace_id":"<тот же 32 hex>","method":"POST","path":"/notes","status":201,"dur_ms":6,"version":"0.7.0"}
notes-1 | {"ts":"2026-09-29T10:00:00.140+00:00","level":"info","msg":"request","trace_id":"<тот же 32 hex>","method":"GET","path":"/notes","status":200,"dur_ms":3,"version":"0.7.0"}
2 db
1 HTTP GET /notes
1 HTTP POST /notes
Если у тебя STORE=file, спанов db не будет: они создаются вокруг PostgreSQL.
Как читать вывод: в логе trace_id равен тому, что ты отправил в заголовке: значит приложение продолжило твой трейс, а не завело свой. Префикс notes-1 | добавляет docker compose logs. В Tempo два серверных спана (по одному на запрос) и два спана db (по одному на каждый запрос к базе): все четыре в одном трейсе, потому что trace_id общий.
Объясни себе:
- Почему имя спана
HTTP GET /notes, а неGET /notes/123с настоящим URL (вспомни урок 8.7 про кардинальность)?
Типичные ошибки:
ModuleNotFoundError: No module named 'opentelemetry': образ собран до правкиrequirements.txt. Пересобери с--build.Failed to export spans batch code: 404, reason: ...в логах приложения: ответил не Alloy, или вOTEL_EXPORTER_OTLP_ENDPOINTуже записан путь/v1/traces(приложение дописывает его само, получается двойной путь). Ожидаетсяhttp://alloy:4318без пути. Если порт не указан, будет не 404, а ошибка соединения (Transient error ... while exporting spans batch, затемFailed to export spans batch due to timeout, max retries or shutdown).- В логах нет поля
trace_id: запрос выполнялся вне активного спана или лог пишется доstart_as_current_span.
Задание 4. Grafana: из лога в трейс и обратно
Цель: подключить Tempo как источник данных и сделать переход между логами и трейсами.
Предскажи: какое поле в Loki-источнике нужно, чтобы значение trace_id в строке лога стало ссылкой на трейс?
Ответ
Derived field (производное поле): регулярное выражение вытаскивает trace_id из строки, а внутренняя ссылка направляет его в источник Tempo.
Шаги:
- Создай
monitoring/grafana/provisioning/datasources/tempo.yml. БлокtracesToLogsV2говорит, как из спана перейти к логам того же трейса:
apiVersion: 1
datasources:
- name: Tempo
uid: tempo
type: tempo
access: proxy
url: http://tempo:3200
jsonData:
# из спана переходим к логам того же trace_id
tracesToLogsV2:
datasourceUid: loki
customQuery: true
query: '{service="notes"} | json | trace_id="$${__span.traceId}"' # $$ даёт литеральный $, иначе Grafana раскроет ${...} как переменную окружения; при customQuery фильтр по trace_id задаёт сам запрос
- В файле источника Loki из урока 8.7 (
monitoring/grafana/provisioning/datasources/loki.yml) убедись, чтоuid: loki, и добавьjsonDataс производным полем. Итоговый файл:
apiVersion: 1
datasources:
- name: Loki
uid: loki
type: loki
access: proxy
url: http://loki:3100
jsonData:
derivedFields:
- name: trace_id
matcherRegex: '"trace_id":"(\w+)"' # вытащить trace_id из JSON-строки
url: '$${__value.raw}' # $$ это экранированный $ в provisioning
datasourceUid: tempo
- Перезапусти Grafana и сгенерируй трафик. Эндпоинт
/slowsql?sec=1есть вapp.pyс урока 8.2: он вызывает в PostgreSQLSELECT pg_sleep(1)(пауза на стороне базы), поэтому в трейсе появится длинный спанdb. Простой/slowтолько спит в приложении, без базы, и спанаdbу него нет:
docker compose -f monitoring/compose.yml restart grafana
# медленный запрос с паузой в PostgreSQL (pg_sleep): в трейсе будет длинный спан db
curl -sk "https://notes.lab/slowsql?sec=1"
for i in 1 2 3; do curl -sk -X POST -d '{"text":"note"}' https://notes.lab/notes > /dev/null; done
- Открой Grafana (
http://localhost:3000), Explore, источник Tempo, режим TraceQL. Выполни запрос:
{ resource.service.name = "notes" && duration > 900ms }
- Открой найденный трейс, в панели спана нажми на иконку логов (Logs for this span). Затем в Explore выбери Loki, запрос
{service="notes"} | json | trace_id != "", раскрой строку и нажми на ссылку у поляtrace_id.
Что должно получиться: в Tempo найден один трейс HTTP GET /slowsql длительностью около 1 с. Из спана открываются логи, в которых ровно эта запись. Из строки лога открывается трейс.
Как читать вывод: в результате TraceQL каждая строка это один трейс с корневым спаном и длительностью. В открытом трейсе полосы показывают длительность и вложенность спанов: длинная полоса db внутри HTTP GET /slowsql значит, что время ушло в базу. Если ссылка у trace_id в логе видна, значит производное поле сработало.
Объясни себе:
- Что тут связывает лог и трейс: тег, время или идентификатор? Почему время не подходит?
Типичные ошибки:
No dataв панели логов у спана: у Loki-источника не совпалuidсdatasourceUid: loki, либо лейблserviceв Loki другой. Сверь с конфигом Alloy из 8.7.Data source tempo was not found: в Loki-источнике указанdatasourceUid: tempo, а Tempo-источник не загрузился. Смотриdocker compose -f monitoring/compose.yml logs grafana | grep -i provisioning.- Ссылки у
trace_idв логе нет: не совпадает регулярка с реальной строкой (формат"trace_id":"..."без пробелов после двоеточия). Сравни сdocker compose logs notes.
Задание 5. Шаг проекта: v7, образ 0.7.0, тег v0.7.0
Цель: зафиксировать состояние проекта после урока.
Предскажи: что покажет curl -k https://notes.lab/ после пересборки, если в compose.yml остался тег 0.6.0?
Ответ
Notes service v0.6.0: версию печатает то, что запущено, а не то, что лежит в app.py. Тег образа и переменная APP_VERSION в compose.yml должны быть обновлены вместе с кодом.
Шаги:
cd ~/notes
# версия образа и приложения (на Ubuntu; на macOS: sed -i '' ...)
grep -n '0\.6\.0' compose.yml .env # до замены: видно, какие строки поменяются
sed -i 's/0\.6\.0/0.7.0/g' compose.yml .env
grep -n '0\.7\.0' compose.yml .env # после замены: те же строки с новой версией
docker build -t notes:0.7.0 .
docker compose up -d
curl -sk https://notes.lab/
# проверка, что в репозитории есть всё нужное для урока
ls monitoring/tempo/tempo.yml monitoring/alloy/config.alloy
git add app.py requirements.txt compose.yml monitoring/
git commit -m "Урок 8.8: OpenTelemetry, Tempo, trace_id в логах"
git tag v0.7.0
git tag --list 'v0.7*'
Разбор. sed -i 's/0\.6\.0/0.7.0/g' compose.yml .env заменяет в обоих файлах 0.6.0 на 0.7.0 (.env хранит APP_VERSION, он закрыт .gitignore и в коммит не попадёт) (точки экранированы \., иначе точка значит «любой символ»; -i правит файл на месте). git add с явными путями добавляет только нужное, а не всё подряд, git tag ставит метку на коммит.
Что должно получиться:
Notes service v0.7.0
monitoring/alloy/config.alloy
monitoring/tempo/tempo.yml
v0.7.0
Эталон состояния после урока: project/notes.
Как читать вывод: сначала идут строки двух grep (в блоке выше их нет, чтобы не загромождать): до замены они показывают строки с 0.6.0 (например, APP_VERSION=0.6.0 в .env), после замены те же строки с 0.7.0. Если до замены вывод пуст, у тебя стоит другая версия: подставь её в sed, иначе замена молча ничего не сделает. Дальше первая строка блока подтверждает, что запущена новая версия. Две следующие: ls нашёл оба файла. Последняя: тег создан.
Объясни себе:
- Почему приложение не падает, если Tempo недоступен? Что происходит с накопленными спанами?
Типичные ошибки:
fatal: pathspec 'monitoring' did not match any files: команда выполнена не из~/notes.Notes service v0.6.0после запуска: не обновлён тег образа вcompose.yml(см. «Предскажи»).
Сломай и почини
Скрипт лежит в репозитории курса, поэтому не качай его из сети по одной ссылке, а возьми из локального клона: git clone ниже скачивает репозиторий целиком в ~/learning-course. Читать скрипт до диагностики не нужно: в нём ответ. После упражнения прочитай его, чтобы увидеть, что именно он менял. Запусти один из сценариев (номер выбери сам):
git clone --depth 1 https://github.com/distinguished-sre/learning.git ~/learning-course 2>/dev/null || git -C ~/learning-course pull -q
bash ~/learning-course/devops/project/notes/break/8.8/break.sh 1
Сценарии 1, 2, 3, 4. Скрипт правит ~/notes/compose.yml, config.alloy или источник Loki в ~/notes/monitoring и перезапускает нужный сервис. После каждого сценария запускай bash ~/learning-course/devops/project/notes/break/8.8/break.sh fix: он возвращает исходное состояние и его можно запускать сколько угодно раз. После запуска сценария сделай несколько запросов (curl -sk https://notes.lab/notes) и открой Grafana. Цель: найти причину по симптомам, не читая скрипт.
Симптом
Один из четырёх: приложение работает, а трейсов в Tempo нет вообще; трейсов нет, а в логе приложения ошибки экспорта; вручную посланный спан (задание 2) не проходит; трейсы и логи есть, но у trace_id в логе нет ссылки на трейс.
Гипотезы
Выпиши минимум по две на симптом. Для «трейсов нет вообще»: Alloy не запущен; порт или протокол не совпадает; Alloy не может передать в Tempo; трейсинг в приложении не включён. Пройди цепочку по участкам, как в теории.
Проверки
Иди от источника к хранилищу и проверяй один участок за раз:
docker compose logs notes | grep -i -E 'export|otel' | tail -5 # ошибки экспорта
docker compose -f monitoring/compose.yml logs alloy | grep -i -E 'error|refused|tls' | tail -5
curl -s http://localhost:3200/ready # Tempo готов?
Разбор. grep -i -E 'export|otel' регистронезависимый поиск строк с любым из двух слов, tail -5 последние пять. Затем повтори ручной спан из задания 2: он проверяет звено «Alloy - Tempo» отдельно от приложения. Если в интерфейсе Alloy (http://localhost:12345) какой-то компонент красный, читай его сообщение.
Исправление
Разбор всех сценариев
1. Порт gRPC вместо HTTP. В OTEL_EXPORTER_OTLP_ENDPOINT у приложения указан http://alloy:4317, а экспортёр говорит по HTTP: в логе приложения ошибки экспорта (Connection reset, Failed to export), трейсов нет. Ручной спан из задания 2 при этом проходит. Починка: адрес http://alloy:4318, docker compose up -d notes.
2. Alloy не может отправить в Tempo. В экспортёре insecure = false: Alloy ждёт TLS, Tempo отвечает без него. В логе Alloy ошибки вроде tls: first record does not look like a TLS handshake, Exporting failed. Ручной спан принимается с кодом 200, но в Tempo не появляется: приём в Alloy работает, отправка дальше нет. Починка: insecure = true (в лаборатории), перезапуск Alloy.
3. Приёмник слушает только внутри контейнера. В config.alloy http-приёмник привязан к 127.0.0.1:4318 вместо 0.0.0.0:4318: изнутри Alloy он доступен, из соседних контейнеров нет. В логе приложения Connection refused, ручной спан с хоста тоже не проходит. Починка: 0.0.0.0:4318, перезапуск Alloy.
4. Сломано производное поле в Loki-источнике. Регулярка ищет "traceid", а в логе ключ trace_id: трейсы и логи есть, но ссылки из лога в трейс нет. Ошибок нигде нет. Починка: вернуть регулярку "trace_id":"(\w+)", перезапустить Grafana. Урок: часть поломок молчит, о них узнаёшь только по тому, что удобной функции нет.
Отдельно про самый частый обрыв трейса в реальной жизни: потерянный traceparent. Если прокси между клиентом и приложением не передаёт заголовок, вместо одного трейса будет два. Проверка: curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' https://notes.lab/headers | jq . покажет, дошёл ли заголовок до приложения.
После разбора верни рабочее состояние:
bash ~/learning-course/devops/project/notes/break/8.8/break.sh fix
ИИ в помощь
Общие правила работы с ИИ-помощником собраны на странице «ИИ-помощник», здесь только сценарии этой темы.
Задача: прочитать водопад трейса.
Трейс запроса GET /slowsql: корневой спан 1010 мс, дочерний спан db 1000 мс, остальное время приходится на корень. Объясни, где ушло время, чьё собственное время у корня и что оптимизировать.
Проверь ответ: собственное время корня 10 мс, а основное время в базе. Типичная ошибка: назвать виновником корень только потому, что его полоса самая длинная.
Задача: найти, где оборвался трейс.
Приложение настроено слать спаны на http://alloy:4317 по OTLP/HTTP, в логе: Failed to export batch, Connection reset by peer. Назови звенья цепочки и порядок проверки.
Проверь ответ: HTTP идёт на порт 4318, gRPC на 4317, и ответ должен указывать на порт и протокол. Типичная ошибка: советовать перезапустить Tempo, хотя обрыв на участке «приложение - Alloy».
Задача: посчитать объём трейсов.
Сервис получает 200 запросов в секунду, на запрос 4 спана по 500 байт. Посчитай объём в сутки без сэмплирования и при сохранении 10 процентов, покажи арифметику.
Проверь ответ: 200 × 4 × 500 × 86 400 это около 34.6 ГБ в сутки, при 10 процентах около 3.5 ГБ. Сверь арифметику сам: нейросети ошибаются в степенях десяти.
Словарик урока
| Термин | Простыми словами |
|---|---|
| Трейс (trace) | запись пути одного запроса через все компоненты |
| Спан (span) | один шаг внутри трейса: начало, длительность, атрибуты |
trace_id |
общий номер трейса, 32 hex-символа |
span_id |
номер одного спана, 16 hex-символов |
| Родительский спан | спан, внутри которого выполняется другой спан |
| hex (шестнадцатеричная запись) | запись числа цифрами 0-9 и буквами a-f |
traceparent |
HTTP-заголовок, который передаёт trace_id следующему сервису |
| Пропагация (propagation) | передача контекста трейса по цепочке сервисов |
| OpenTelemetry (OTel) | стандарт и библиотеки для метрик, логов и трейсов |
| SDK | библиотека в приложении, которая создаёт и накапливает спаны |
| OTLP | протокол передачи телеметрии: gRPC на 4317, HTTP на 4318 |
| Сборщик (collector) | программа между приложением и хранилищем, у нас Alloy |
| Tempo | хранилище трейсов от Grafana |
| TraceQL | язык запросов Tempo для поиска трейсов и спанов |
| Сэмплирование (sampling) | выбор, какую долю трейсов сохранять |
| Ресурс (resource) | описание источника спанов: имя сервиса, версия |
| Атрибут спана | пара «ключ=значение» с подробностями шага |
| Derived field | поле в Loki-источнике Grafana, которое превращает часть строки лога в ссылку |
| gRPC | способ вызова по сети с компактной двоичной упаковкой данных, порт OTLP 4317 |
| Статус спана | оценка шага: UNSET, OK или ERROR, ставит приложение |
| Собственное время спана | длительность спана минус длительность его дочерних спанов |
Вопросы с собеседований
Раздел для повторения: ответь вслух, потом открой ответ. Вопросы с пометкой «часто» задают почти на каждом собеседовании по теме урока: начни с них.
1. [junior] [часто] Чем трейсы отличаются от логов и метрик?
Ответ
Метрики отвечают «сколько и как часто», логи «что случилось», трейсы «где в цепочке ушло время». Трейс показывает путь одного запроса с длительностью каждого шага.
Что хотят услышать: три сигнала не заменяют друг друга; трейс нужен, когда запрос проходит через несколько компонентов; метрика даёт агрегат, трейс даёт конкретный случай.
Красный флаг: «трейсы это просто логи с временем».
2. [junior] [часто] Что такое span и как он связан с trace_id?
Ответ
Span это одна операция с началом и длительностью. Все спаны одного запроса имеют общий trace_id и образуют дерево по parent_span_id.
Что хотят услышать: root span, child span, атрибуты, статус (ошибка), длительность.
Красный флаг: путает trace_id и span_id или не понимает, что такое родитель.
3. [middle] [часто] Что такое сэмплирование и какое выбрать для прода?
Ответ
Сохранение части трейсов из-за стоимости хранения. Head решает в начале запроса и прост, tail решает по итогу и оставляет ошибки и медленные запросы. Для прода обычно tail в сборщике плюс небольшая доля обычных запросов.
Что хотят услышать: компромисс цена против полноты; tail требует буферизации спанов в сборщике; ошибки и p99 не теряются.
Красный флаг: «сэмплирование не нужно, храним всё» для нагруженного сервиса.
4. [junior] [на скорость] Что такое OTLP и какие у него порты?
Ответ
Протокол OpenTelemetry для передачи телеметрии. По gRPC порт 4317, по HTTP 4318 (/v1/traces).
Что хотят услышать: два транспорта, ошибка «HTTP на порт gRPC», OTLP не привязан к конкретному хранилищу.
Красный флаг: «OTLP это формат Jaeger».
5. [junior] [на скорость] Что такое traceparent?
Ответ
Заголовок W3C Trace Context: версия, trace_id, span_id родителя, флаги. Клиент кладёт его в исходящий запрос, сервер продолжает трейс.
Что хотят услышать: это механизм пропагации между сервисами; формат 00-<32hex>-<16hex>-01; флаг сэмплирования.
Красный флаг: не знает, как трейс связывается между двумя сервисами.
6. [junior] Зачем приложению нужен сборщик, а не отправка спанов сразу в хранилище?
Ответ
Сборщик буферизует и батчит спаны, переживает кратковременные сбои хранилища, может добавлять атрибуты, фильтровать и сэмплировать. Приложение знает один стабильный адрес и не привязано к конкретному хранилищу: смена Jaeger на Tempo не требует пересборки.
Что хотят услышать: буфер и батчи, независимость от хранилища, место для сэмплирования и фильтрации.
Красный флаг: «сборщик просто лишний хоп».
7. [middle] В Tempo вместо одного трейса запроса два несвязанных: nginx и приложение. Что проверяешь?
Ответ
Иду по цепочке: доходит ли traceparent до приложения (/headers), не обнуляет ли его прокси, вызывает ли приложение extract. Если nginx сам не создаёт спаны, то трейс начинается в приложении, и два трейса значит, что заголовок теряется между клиентом и сервисом.
Что хотят услышать: пропагация контекста как первая гипотеза; проверка заголовков на каждом хопе; proxy_set_header; после починки один trace_id в логах обоих участников.
Красный флаг: «перезапущу Tempo».
8. [middle] Приложение работает, трейсов в Tempo нет. Твои действия?
Ответ
Иду от источника: включён ли экспорт (endpoint не пуст), что пишет exporter в лог приложения, отвечает ли приёмник на тестовый спан вручную, порты и протокол (4317 gRPC против 4318 HTTP), потом ошибки Alloy при отправке в Tempo, потом Tempo /ready и запрос по trace_id с учётом задержки.
Что хотят услышать: деление цепочки на участки и проверка каждого; ручной OTLP-спан через curl; путаница портов как частая причина.
Красный флаг: правит сразу всё и не проверяет по участкам.
9. [middle] Как связать лог, метрику и трейс?
Ответ
Пишу trace_id в каждую JSON-строку лога, в Grafana настраиваю derived field в Loki-источнике и tracesToLogsV2 в Tempo-источнике. Для метрик используют exemplars: к точке гистограммы прикреплён trace_id конкретного запроса.
Что хотят услышать: общий идентификатор, а не время; двунаправленные ссылки в Grafana; exemplars; trace_id не является лейблом метрики или Loki.
Красный флаг: предлагает добавить trace_id лейблом в Prometheus или Loki.
10. [middle] Запросы стали медленнее: p95 вырос с 100 мс до 800 мс. Как найдёшь причину с помощью трейсов?
Ответ
Беру по метрике время всплеска, в Tempo ищу TraceQL { resource.service.name = "notes" && duration > 500ms }, открываю несколько трейсов и смотрю, какой спан занимает собственное время: db, внешний вызов или сама обработка. Затем логи по trace_id этого запроса и, при необходимости, метрики БД.
Что хотят услышать: от метрики к трейсу, анализ структуры спанов, TraceQL, сравнение с нормальным трейсом.
Красный флаг: только «посмотрю логи» и не знает, как найти медленные конкретные запросы.
11. [junior] Что такое OpenTelemetry и чем он отличается от Jaeger или Tempo?
Ответ
OpenTelemetry (OTel) - открытый стандарт и набор инструментов для получения телеметрии: SDK для языков программирования, протокол OTLP и Collector. Он описывает, как создавать и передавать метрики, логи и трейсы. Jaeger и Tempo - это хранилища и интерфейсы для трейсов, куда данные в итоге попадают. Поэтому приложение инструментируется один раз через OTel, а бэкенд можно поменять без переписывания кода. OTel сам трейсы не хранит.
Что хотят услышать: OTel это стандарт, SDK и Collector, Jaeger и Tempo это хранилища, независимость приложения от бэкенда.
Красный флаг: «OpenTelemetry это база данных для трейсов».
12. [junior] Зачем у ресурса атрибут service.name и что будет, если его не задать?
Ответ
service.name - атрибут ресурса, по которому бэкенд группирует трейсы и показывает сервисы на карте зависимостей. Если имя не задать, SDK подставит значение вроде unknown_service, и все сервисы в интерфейсе смешаются в одну кучу. Я задаю его через переменную окружения OTEL_SERVICE_NAME или в конфигурации SDK, отдельно для каждого сервиса. Атрибуты ресурса (service.name, версия, окружение) описывают источник телеметрии в целом, а атрибуты спана - конкретную операцию.
Что хотят услышать: группировка по service.name, unknown_service без него, OTEL_SERVICE_NAME, ресурс против атрибутов спана.
Красный флаг: одинаковое имя на всех сервисах.
Проверено на версиях
Не прогонялось: Tempo, Alloy, Grafana и приложение v7 не запускались, конфиги и запросы взяты из предыдущей редакции урока и сверены с эталоном project/notes/versions/v7.py (чтением), а не выполнением; схема конфига Tempo сверена со стендом load-tester (проверен в CI), а сам урок не прогонялся. break.sh проверен через shellcheck и прогоном на копии файлов без Docker.
- Ubuntu: 26.04 LTS и 24.04 LTS
- Docker Engine и Compose: версии из урока 4.1
- Grafana Tempo: 2.10.8
- Grafana Alloy: v1.20.1
- Grafana: 13.2.2
- Loki: 3.7.8
- Python: 3.13
- OpenTelemetry API, SDK и OTLP/HTTP-экспортёр для Python: 1.45.2 (как в эталонном
requirements.txt)
Итог урока: ты умеешь
- объяснить, что такое трейс, спан,
trace_idиtraceparent - описать путь спана: приложение, Alloy (OTLP 4318), Tempo, Grafana
- прочитать диаграмму трейса и найти спан, в котором ушло время
- отправить тестовый спан по OTLP/HTTP через curl и найти его в Tempo по
trace_id - найти медленный запрос в Grafana запросом TraceQL
- перейти из строки лога в трейс и из спана в логи по
trace_id - пройти цепочку «приложение - Alloy - Tempo» по участкам и найти обрыв
- отличить проблему порта и протокола OTLP (4317 против 4318) от других поломок
- собрать образ 0.7.0 и поставить тег v0.7.0
Дальше: Урок 8.9: Мониторинг в Kubernetes: kube-prometheus-stack
Проверь себя
Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.
Тест работает с включённым JavaScript.