Диагностика: каналы, async-контекст и профили

diagnostics_channel: инструментировать без monkey-patching

Старый способ добавить трейсинг или метрики в библиотеку — это monkey-patch её прототипа: обернуть http.request, подменить метод драйвера, — что молча ломается на следующем апгрейде и привязывает твой код наблюдаемости к внутренностям. node:diagnostics_channel — встроенная in-process шина pub/sub, появившаяся в Node 15, — заменяет этот подход. Продюсер публикует именованные сообщения; подписчики получают их синхронно. Core, undici и http уже выставляют каналы, так что ты инструментируешь их, не трогая их код.

Свойство производительности, которое делает безопасным оставлять это в горячих путях, — hasSubscribers. publish без слушателей по сути бесплатен, так что библиотека может оградить стоимость сборки сообщения и не платить ничего, когда никто не смотрит.

import diagnostics_channel from "node:diagnostics_channel";

const channel = diagnostics_channel.channel("app:db:query");

// продюсер (в обёртке БД) — платим за сборку payload только если наблюдают
function runQuery(sql, params) {
  if (channel.hasSubscribers) {
    channel.publish({ sql, params, startedAt: performance.now() });
  }
  return driver.query(sql, params);
}

// подписчик (в твоей настройке трейсинга) — подключаемся с нулевой связностью с обёрткой
channel.subscribe((message) => {
  metrics.increment("db.query", { sql: message.sql });
});

Компромисс против event emitter или обёртки: каналы синхронны и не упорядочены между продюсерами, так что подписчик обязан быть быстрым и не должен бросать в вызов продюсера. Выигрыш — расцепление: ты можешь подписаться на встроенные каналы запросов undici для распределённого трейсинга без единой строки патчинга, и инструментация переживает апгрейды библиотеки.

AsyncLocalStorage: контекст запроса, переживающий await

Баг из хука — traceId, потерянный двумя слоями ниже, — это канонический случай для AsyncLocalStorage (из node:async_hooks — хранилище, автоматически привязанное к текущему async-контексту, без передачи аргументов). Он даёт тебе хранилище, заскоупленное на асинхронное дерево вызовов: ты вызываешь als.run(store, fn) один раз на границе запроса, и любой код, достижимый из fn — сквозь await, setTimeout, цепочки промисов, колбэки библиотек, — может вызвать als.getStore() и прочитать тот же store. Ты больше никогда не передаёшь id аргументом.

import { AsyncLocalStorage } from "node:async_hooks";

const als = new AsyncLocalStorage();

// на границе: открыть контекст для этого запроса
app.use((req, res, next) => {
  const store = { traceId: req.headers["x-trace-id"] ?? crypto.randomUUID() };
  als.run(store, () => next());
});

// где угодно ниже по потоку, как угодно глубоко, без всякой проводки:
function log(msg) {
  const { traceId } = als.getStore() ?? {};
  logger.info({ traceId, msg });
}

Сравни это с переменной уровня модуля: глобал разделяется между всеми конкурентными запросами, так что под нагрузкой запрос B перезаписывает id запроса A, и твои трассы перемешиваются в бессмыслицу. AsyncLocalStorage держит отдельный store на каждый async-контекст, что ровно та изоляция, которая нужна серверу. Стоимость реальна, но ограничена — он едет на async_hooks, так что есть накладной расход на каждую async-операцию; держи store маленьким (id и флаги, а не большие объекты) — и ты платишь однозначные проценты в типичных обработчиках запросов.

Сигналы и профилирование по запросу

Когда контейнер попадает под rolling-обновление или процесс теряет память на staging, нужно действовать на живом процессе без рестарта — именно для этого и существуют сигналы и профилирование по запросу. Долгоживущий процесс общается со своим оператором через сигналы. Оркестраторы шлют SIGTERM, чтобы попросить graceful shutdown — ты получаешь окно, чтобы перестать принимать новую работу, слить запросы в полёте, закрыть пулы БД и выйти; если ты его игнорируешь, Kubernetes следом шлёт SIGKILL после grace-периода (30с по умолчанию) и обрубает тебя посреди запроса. SIGINT — это Ctrl-C в терминале. SIGUSR1 особый: Node по умолчанию открывает инспектор при его получении, так что ты можешь подключить дебаггер к живому процессу без рестарта.

// graceful shutdown: перестать принимать → слить → закрыть зависимости → выйти
process.on("SIGTERM", async () => {
  server.close();             // перестать принимать новые соединения
  await drainInFlight();      // дать активным запросам завершиться
  await db.end();             // закрыть пулы / сбросить
  process.exit(0);
});

Когда нужно увидеть, почему процесс медленный или течёт, профилируй его по запросу. Запусти с --cpu-prof (или --heap-prof), и Node запишет .cpuprofile (или .heapprofile) на выходе, который ты открываешь в панели Performance/Memory Chrome DevTools; --diagnostic-dir управляет тем, куда падают файлы. Для жёсткого краша включи core dumps (ulimit -c unlimited и --abort-on-uncaught-exception, чтобы дампить на непойманном throw) и разбирай дамп посмертно с llnode/lldb. Сквозная идея: ничто из этого не требует править код приложения, так что это безопасно добавить к плохо ведущему себя production-процессу.