instrumentation.ts и трассировка: один register() на процесс, один trace на запрос и счёт за выборку

register() выполняется раз на процесс — всё остальное стреляет в ногу

instrumentation.ts живёт в корне проекта (рядом с app/ или внутри src/) и экспортирует одну функцию с одной гарантией: Next.js вызывает register(), когда новый серверный процесс загружается, до обслуживания первого запроса. Эта гарантия — ровно то, что нужно OTel SDK (OpenTelemetry — вендор-нейтральный стандарт трассировки): tracer provider должен существовать до первой инструментированной операции, и существовать один раз. Любая альтернатива нарушает одну из половин. Инициализация на уровне модуля в каком-нибудь lib/otel.ts, импортируемом из layout, перевыполняется на каждый бандл маршрута (на serverless каждый роут компилируется отдельной точкой входа) и дважды регистрирует провайдеры. Хуже того, сам register() выполняется в обоих рантаймах приложения — а Node SDK импортирует node:async_hooks и компанию, которых в edge-рантайме не существует. Каноническая форма — guard по рантайму с динамическим импортом:

// instrumentation.ts — единственный файл, который Next.js обещает выполнить раз на серверный процесс
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node'); // NodeSDK тянет node:async_hooks — не должен попасть в edge-бандл
  }
}

// instrumentation.node.ts — полный контроль: экспортёр, resource, семплер
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  serviceName: 'storefront',
  traceExporter: new OTLPTraceExporter({ url: process.env.OTLP_ENDPOINT }),
});
sdk.start();

Если кастомный конвейер не нужен, @vercel/otel сворачивает всё это в registerOTel({ serviceName: 'storefront' }) внутри register() — пакет знает о рантаймах и сам выбирает безопасные внутренности. Две честные оговорки, на которых спотыкаются и сеньоры. Первая: «раз на процесс» значит раз на холодный старт, а не раз на деплой — на serverless процессов много и они конкурентны, так что любое состояние, построенное в register(), — счётчики, решения о выборке в памяти — существует на инстанс, а не глобально. Вторая: тот же файл экспортирует onRequestError — хук, который Next.js вызывает при серверных ошибках с контекстом запроса; это естественное место отправлять digest-ы ошибок из прошлого урока в трекер, а не выскребать их из stdout.

Один запрос — один trace: встроенные span-ы и передача контекста

С зарегистрированным трейсером Next.js издаёт span-ы для собственной работы — без изменений кода: span на рендер маршрута (с именем вида render route (app) /dashboard), span на каждый инструментированный fetch, span-ы на выполнение route handler-ов, с атрибутами вроде шаблона маршрута (NEXT_OTEL_VERBOSE=1 расширяет набор). Дисциплина именования важнее, чем выглядит: span называют по шаблону маршрута, никогда — по конкретному URL: /orders/[id], а не /orders/9381, потому что каждое уникальное имя — новая серия в вашем бэкенде, и имя-на-заказ превращает дашборд в таблицу по клиентам.

Передача контекста — то, что превращает три силоса мониторинга в одну картину. Инструментированный fetch вставляет W3C-заголовок traceparent — 00-<trace-id>-<span-id>-<flags> — в исходящие запросы из серверных компонентов, действий и route handler-ов. Любой бэкенд с OTel SDK на любом языке читает его и продолжает тот же trace. Водопад тогда тянется от браузера через рендер RSC к API заказов и его базе, один trace id из конца в конец — и дежурный вопрос «куда ушли 800 мс» становится поиском, а не тредом на три команды в Slack. Если бэкенд вместо этого появляется отдельным корневым span-ом — первый подозреваемый: прокси или API-шлюз, срезающий traceparent по дороге.

Выборка и кардинальность: счёт — это проектное ограничение

Прежде чем включать трассировку, спросите себя: при вашем трафике сколько span-ов будет лететь в минуту — и за какими из них вы когда-нибудь пойдёте в поиск? Числа из пролога обобщаются. Span сериализуется примерно в 300–800 байт с обычными атрибутами; 31 млн span-ов в день — порядка 10–25 ГБ в день на приёме, а вендоры берут за гигабайт или за миллион span-ов — в любом случае span на каждый HIT дата-кеша — это плата за запись того, что ничего не произошло. Рычаги, по убыванию отдачи. Первый: выбрасывайте span-ы, которые никогда не будете запрашивать — фильтруйте span-ы кеш-хитов fetch и шум статики в span-процессоре или коллекторе до того, как они начнут стоить денег. Второй: head-выборка — ParentBasedSampler(TraceIdRatioBasedSampler(0.1)) — решает в корне трейса и почти бесплатна, но слепа: она выбрасывает трейсы с ошибками и медленные трейсы ровно с той же частотой, что и здоровые, — так команда из пролога и потеряла свой инцидент. Третий: tail-выборка в коллекторе: буферизовать полные трейсы и оставлять всё с ошибкой, всё медленнее порога плюс несколько процентов здоровой базы. Это политика, которую вы на самом деле хотите, и её честная цена операционна: коллектор держит каждый незавершённый trace в памяти на окно решения (обычно 10–30 с; при 600 rps это тысячи буферизованных трейсов), и теперь вы эксплуатируете и масштабируете коллектор. Вместе три рычага переводят вас из режима «платить за всё» в режим «платить только за то, что запросишь»; пропустите первые два — и придёте к tail-выборке с датасетом, который уже слишком дорого содержать.

Кардинальность — тихая половина счёта. Атрибуты индексируются; положите user id, id сессии или полный URL в атрибуты span-а — и бэкенд построит запись индекса на каждого пользователя. Дисциплина, переживающая аудиты: шаблон маршрута, метод, статус, регион — идентификаторы живут в логах (с ключом trace id), а не в индексах трейсов. Накладные расходы рантайма, ради честности, — самая дешёвая часть истории: создание span-а стоит единицы микросекунд CPU, а BatchSpanProcessor экспортирует вне горячего пути, так что типичное приложение платит за трассировку 1–3% CPU. Болят счёт и кардинальность — поэтому стратегия выборки относится к дизайн-ревью, а не к панике после первого инвойса.