Распределённый трейсинг с OpenTelemetry

Что такое трейс: span, traceId и цепочка родителей

Трейс — это всё путешествие одного запроса, представленное как дерево. Каждый узел — это span: одна операция со временем — начало, конец и набор атрибутов (HTTP-маршрут, SQL-выражение, статус). Span связаны двумя id. traceId общий для каждого span запроса — это ключ соединения для всего дерева. spanId идентифицирует один span, и каждый span записывает свой родительский spanId, что и придаёт дереву форму: span у api — корень, span у orders — его ребёнок, span у payments — ребёнок того, и так далее.

// Один span = одна операция. Трейсер создаёт его; ты ставишь атрибуты и заканчиваешь.
const tracer = trace.getTracer('orders');

await tracer.startActiveSpan('chargeCustomer', async (span) => {
  span.setAttribute('order.id', orderId);
  span.setAttribute('payment.amount', amount);
  try {
    return await this.payments.charge(orderId, amount);
  } catch (err) {
    span.recordException(err);
    span.setStatus({ code: SpanStatusCode.ERROR });
    throw err;
  } finally {
    span.end(); // start→end is THIS span's duration on the trace
  }
});

С этим деревом инцидент checkout отвечает на себя сам в один экран: открываешь трейс, видишь четыре span, разложенные на таймлайне, и span у payments видимо шириной 2.6с, а остальные три — тонкие щепки. Углубляешься в него — и находишь, что payments зовёт inventory синхронно в цикле, один round trip на позицию заказа. Ни один дашборд не мог это показать, потому что каждый отдельный вызов inventory был быстрым — медленным был последовательный fan-out, сумма, а сумма существует только в трейсе.

Проброс контекста: механизм, делающий один трейс из четырёх сервисов

Сложная часть — не создавать span, это делает авто-инструментация. Сложная часть — держать каждый span в одном и том же трейсе, пока запрос пересекает границы. Для этого trace context — traceId, текущий spanId и флаг сэмплинга — должен путешествовать через два разных вида границ.

Между сервисами, по сети, контекст едет в W3C HTTP-заголовке traceparent (стандартизированный заголовок трассировки: версия-traceId-spanId-флаги). Вызывающая сторона инжектит его в исходящие заголовки запроса; вызываемая сторона извлекает его и продолжает трейс, а не начинает новый.

// traceparent: version-traceId-parentSpanId-flags
// 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
//    └─ 32 hex traceId ──────────────┘ └─ 16 hex spanId ┘ └ sampled
// Вызывающая сторона инжектит этот заголовок; вызываемая извлекает его, и span orders
// становится ДОЧЕРНИМ к span api — тот же traceId, новый spanId, parent = api.

Внутри процесса, через await и колбэки, нет заголовка, который понесёт контекст, — поэтому Node-менеджер контекста OTel хранит «текущий активный span» в AsyncLocalStorage. ALS — это механизм V8, который держит значение прикреплённым к одной логической async-цепочке вызовов: span, начатый в guard, всё ещё текущий span внутри handler и внутри вызова pg, который делает handler, потому что все они выполняются внутри одной отслеживаемой ALS-цепочки. Вот почему запрос к БД авто-вкладывается под span запроса, а ты ничего не передаёшь руками.

Режим отказа симметричен: потеряй контекст на любой из границ — и трейс фрагментируется. Пропусти traceparent на исходящем вызове — и вызываемая сторона начнёт свежий корневой трейс. Вырвись из ALS-цепочки — fire-and-forget неотавайченный промис, голый setTimeout, хоп через очередь без проброса — и продолжение выполнится без активного span, так что OTel не видит родителя и открывает новый корень. В любом случае запрос, который должен быть одним деревом, становится несколькими несвязанными фрагментами, и ты снова таращишься на несвязанные трейсы, не в силах проследить запрос из конца в конец.

Подключение OTel к Nest: bootstrap до приложения

Единственное правило, которое кусает всех: инструментация работает, monkey-patch’ая модули, которые трейсит (http, express, pg, ядро Nest), так что SDK должен стартовать до того, как твоё приложение импортирует эти модули. На практике ты кладёшь NodeSDK в отдельный файл и грузишь его первым — node --require ./tracing.js dist/main.js или import './tracing' самой первой строкой main.ts.

// tracing.ts — MUST be loaded before the Nest app so it patches http/pg/nest first
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';

const sdk = new NodeSDK({
  // auto-instruments http, express, @nestjs/core, pg — spans appear with no app code
  instrumentations: [getNodeAutoInstrumentations()],
  // head sampling: keep 10% of traces (see the sampling section)
  sampler: new TraceIdRatioBasedSampler(0.1),
});
sdk.start();

Как только это загружено, каждый HTTP-запрос и каждый запрос pg производят span автоматически. Ты добавляешь ручные span (tracer.startActiveSpan) только вокруг бизнес-операций, которые авто-инструментация не может назвать, — «зарезервировать остаток», «оценить риск». И ты замыкаешь круг структурным логированием из L01: инжектишь активный traceId в каждую строку лога. Это единственное поле — ключ корреляции: найди медленный трейс, скопируй его traceId и подними каждый лог из каждого сервиса для ровно этого запроса. Логи отвечают что случилось; трейс отвечает куда ушло время; traceId — это соединение между ними.

// L01's logger, now trace-aware: every line carries the active traceId
const span = trace.getActiveSpan();
const ctx = span?.spanContext();
this.logger.log({ msg: 'charge failed', orderId, traceId: ctx?.traceId, spanId: ctx?.spanId });
// now one traceId pulls every log from every service for this exact request

Сэмплинг: ты не можешь позволить себе хранить каждый трейс

Прежде чем добавлять трейсинг в продакшен-сервис, спроси себя: при 5 000 RPS сколько данных span ты реально готов хранить и оплачивать? Ответ определяет, к какой из двух стратегий ниже ты потянешься. Трейсить каждый запрос дорого — хранение span и пропускная способность экспорта доминируют, а неограниченные span или атрибуты на запрос добавляют реальную цену. Поэтому ты сэмплируешь: часть трейсов оставляешь, остальное роняешь. Есть две стратегии, и компромисс между ними — это сеньорское решение.

Head sampling решает на корне, до выполнения запроса, обычно по доле: TraceIdRatioBasedSampler(0.1) оставляет 10%. Дёшево и не требует доп. инфраструктуры — но решение слепое. Оно не может знать, что запрос, который ты уронил, был тем самым, что занял 3 секунды или бросил 500, так что при низкой доле ты систематически пропускаешь редкие медленные и падающие запросы — ровно те, что тебе и нужны.

Tail sampling решает после того, как запрос завершился, когда исход известен: оставь все ошибки и все медленные трейсы, сэмплируй малую долю скучных быстрых. Оно ловит редкий плохой запрос, который head sampling роняет. Цена в том, что его нельзя решить в процессе — каждый span трейса должен где-то буферизоваться, пока трейс не завершится и не вынесется вердикт оставить/уронить, а значит ты должен гонять OpenTelemetry Collector как буферизующий ярус между твоими сервисами и бэкендом.