Навигация

Логирование и наблюдаемость

Сервис падает в три часа ночи, и первое, что нужно понять, — что именно сломалось: конкретный запрос, весь инстанс или зависимость. Ответ зависит от того, какие сигналы сервис оставил до аварии. Ниже — как построить эти сигналы в Node: структурные логи, request-id, health checks, метрики и трассы, — и как не утонуть в их объёме.

Содержание

  1. Три столпа наблюдаемости
  2. Структурные логи и pino
  3. request-id и контекст запроса
  4. Уровни, объём и стоимость
  5. Health checks: liveness и readiness
  6. Метрики: RED и USE
  7. Трассировка через OpenTelemetry
  8. Корреляция сигналов
  9. Алерты и SLO
  10. Практика: observability в TaskFlow
  11. Частые ошибки
  12. Ключевые тезисы для интервью
  13. Заключение
  14. Полезные ссылки

Три столпа наблюдаемости

Наблюдаемость строят на трёх типах сигналов, и они отвечают на разные вопросы:

СигналВопросОбъёмЧто хранят
ЛогиЧто произошло с этим запросом?Растёт с числом запросовСобытия с полями и контекстом
МетрикиСколько таких событий и как они распределены?Почти не растётАгрегаты: счётчики, гистограммы, gauge
ТрейсыГде запрос провёл время и кого вызвал?Растёт с числом запросов, поэтому сэмплируетсяДерево спанов с длительностями

Метрика дешёвая и потому живёт годами, но не говорит, какой именно пользователь получил 500. Лог знает подробности, но по нему дорого считать процент ошибок за месяц. Трейс показывает, что 80% времени ушло в запрос к базе, но не объясняет, почему этот запрос был медленным на конкретных данных.

Отсюда практическое правило: алерт ставят на метрику, причину ищут в трейсе, детали читают в логе. Если сервис умеет только писать строки в stdout, у него есть логи, но нет наблюдаемости.

Чем это отличается от браузера: там разработчик видит консоль и DevTools конкретного пользователя, а на сервере — тысячи параллельных запросов и ни одного «экрана». Контекст приходится восстанавливать по идентификаторам, которые сервис сам проставляет. Разница между клиентским и серверным логированием разобрана в статье «Асинхронность в Node.js».

Почему console.log не работает в проде

console.log('task updated', task.id) выглядит безобидно, пока сервис запущен на ноутбуке. В проде у этой строки пять проблем:

  • Нет уровня. Нельзя отделить отладочный шум от ошибки и настроить фильтр на уровне сборщика логов.
  • Нет структуры. Поля склеены в текст: чтобы найти все записи по task.id = 42, нужно парсить строку регуляркой, и она сломается на следующем изменении формата.
  • Нет контекста. В записи нет requestId, userId, названия сервиса и версии — при нескольких инстансах невозможно понять, кто и в рамках какого запроса это написал.
  • Нет redaction. console.log(req.headers) однажды запишет authorization и cookie в хранилище, которое читают все.
  • Нет управления потоком. Запись в stdout синхронна на части платформ и может блокировать Event Loop; многострочный стектрейс к тому же ломает построчные парсеры.

console.log остаётся нормальным инструментом локальной отладки. В проде он заменяется логгером, который пишет JSON-строки с предсказуемой схемой.


Структурные логи и pino

pino — самый распространённый логгер для Node: он пишет JSON без форматирования в горячем пути и умеет сериализаторы, redaction и дочерние логгеры. Базовая настройка выглядит так:

// src/lib/logger.js
import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  base: { service: 'taskflow-api', env: process.env.NODE_ENV },
  timestamp: pino.stdTimeFunctions.isoTime,
  redact: {
    paths: [
      'req.headers.authorization',
      'req.headers.cookie',
      '*.password',
      '*.token',
      '*.refreshToken',
    ],
    censor: '[redacted]',
  },
  serializers: {
    err: pino.stdSerializers.err,
    req: pino.stdSerializers.req,
    res: pino.stdSerializers.res,
  },
});

Одна запись выглядит как одна строка JSON:

{"level":30,"time":"2026-11-05T10:15:31.482Z","service":"taskflow-api","env":"production","requestId":"b1f5c7a2-...","msg":"task updated","taskId":42,"userId":7}

Из этой строки сборщик логов (Loki, Elasticsearch, CloudWatch) достаёт поля без регулярок: level=30, requestId, taskId. По ним строят фильтры и графики, а по level настраивают маршрутизацию — error в канал дежурного, info в общее хранилище.

Уровни

УровеньЧислоКогда использовать
trace10Трассировка циклов и ветвлений, почти никогда в проде
debug20Диагностика, включается точечно
info30Значимые события: старт, миграции, бизнес-операции
warn40Ожидаемая деградация: retry, 4xx, медленный запрос
error50Ошибка, которую кто-то должен разобрать
fatal60Процесс не может продолжать работу

Уровень — это не «важность текста», а решение о судьбе записи. Если писать error на каждый неудачный логин, алерты по ошибкам перестанут что-либо значить. Ожидаемые отказы (401, 404, 422) — это warn или вообще часть метрики, а error — сигнал о том, что сервис повёл себя не так, как задумано.

Сериализаторы и redaction

Сериализаторы превращают объекты в плоские структуры. pino.stdSerializers.err оставляет type, message, stack и причину, req — метод, URL и заголовки, res — статус и заголовки, всё без тела. Без них logger.error({ err }) может потерять стек или, наоборот, вытащить в лог весь объект запроса.

Redaction вырезает поля до записи:

logger.info({ user: { email, password } }, 'user created');
// {"password":"[redacted]", ...}

Список путей задаётся для конкретной схемы логов и должен покрывать authorization, cookie, set-cookie, поля с токенами, паролями, секретами и персональными данными. Проверять redaction нужно тестом: опечатка в пути не роняет приложение, а тихо пропускает секрет в хранилище.

Тело запроса и ответа целиком не логируют почти никогда: там пользовательские данные и большой объём. Если тело нужно для разбора инцидента, логируют конкретные поля и включают это на время.

Дочерние логгеры

Дочерний логгер добавляет поля ко всем записям, не повторяя их в каждом вызове:

const log = logger.child({ requestId, userId });
log.info({ taskId }, 'task updated');

В обработчике запроса такой логгер создают один раз. Но протаскивать его через сервисный слой неудобно, а забыть — легко. Поэтому контекст запроса обычно хранят в AsyncLocalStorage, а логгер добавляет его автоматически — об этом следующий раздел.


request-id и контекст запроса

request-id — это идентификатор, который связывает все записи одного запроса: вход в middleware, обращение к базе, ошибку и ответ. Его принимают из заголовка x-request-id, если он пришёл от прокси или клиента, иначе генерируют:

// src/middleware/context.js
import { randomUUID } from 'node:crypto';
import { AsyncLocalStorage } from 'node:async_hooks';

export const requestStore = new AsyncLocalStorage();

export function requestContext(req, res, next) {
  const requestId = req.id ?? req.get('x-request-id') ?? randomUUID();
  req.id = requestId;
  res.setHeader('x-request-id', requestId);

  requestStore.run({ requestId }, () => next());
}

AsyncLocalStorage из node:async_hooks переносит контекст через await, таймеры и колбэки ввода-вывода: любая функция внутри run() видит свой store, не получая его параметром. Это тот же механизм, которым пользуются для tenant, пользователя и клиента транзакции; подробнее — в статье «Асинхронность в Node.js».

Логгер подмешивает контекст в каждую запись через mixin:

import { requestStore } from '../middleware/context.js';

export const logger = pino({
  // ...
  mixin() {
    const store = requestStore.getStore();
    return store ? { requestId: store.requestId } : {};
  },
});

mixin вызывается только для записей, прошедших фильтр уровня, поэтому на выключенном debug он почти ничего не стоит. Важно не использовать enterWith в middleware: он меняет контекст текущего исполнения и легко протекает на следующий запрос в том же стеке.

Access log

Логировать каждый запрос вручную в каждом обработчике не нужно — это делает middleware. pino-http совмещает access log, генерацию req.id и дочерний логгер:

import pinoHttp from 'pino-http';

app.use(pinoHttp({
  logger,
  genReqId: (req) => req.id, // уже выставлен в requestContext
  customLogLevel: (req, res, err) => {
    if (err || res.statusCode >= 500) return 'error';
    if (res.statusCode >= 400) return 'warn';
    return 'info';
  },
  autoLogging: {
    ignore: (req) => req.url.startsWith('/health/'),
  },
}));

requestContext должен быть зарегистрирован раньше pino-http, иначе req.id ещё не существует и genReqId вернёт undefined.

В записи появляются метод, URL, статус и responseTime. Health-проверки исключены: они идут каждые несколько секунд и создают шум, в котором теряются настоящие запросы.

Access log отвечает на вопрос «сколько длился запрос с точки зрения клиента», но не показывает, где внутри ушло время. Для этого нужен трейс, а для агрегатов — метрики.

Передача контекста дальше

Внутри процесса AsyncLocalStorage работает сам. За его пределами — нет: исходящий HTTP-запрос, задача в очереди и сообщение в брокере начинаются с чистого контекста. Поэтому requestId и traceparent кладут в исходящие заголовки явно:

import { context, propagation } from '@opentelemetry/api';

const carrier = {};
propagation.inject(context.active(), carrier);

await fetch(`${billingUrl}/invoices`, {
  headers: {
    'x-request-id': requestStore.getStore()?.requestId ?? '',
    ...carrier, // traceparent и tracestate
  },
});

На принимающей стороне заголовок снова становится контекстом. Без этого шага цепочка рвётся на первом же вызове другого сервиса, и в логах биллинга не будет идентификатора, по которому его можно связать с TaskFlow. Подробнее о клиентах — в статье «HTTP-клиенты в Node.js».


Уровни, объём и стоимость

Логи — единственный сигнал, объём которого растёт линейно с трафиком. Сервис на 1000 RPS с тремя строками на запрос пишет около 260 миллионов записей в сутки; при цене хранения это заметная статья бюджета, а при поиске — заметная задержка.

Что с этим делают:

  • Уровень info в проде, debug — по требованию. logger.level = 'debug' можно переключить на время разбора инцидента, но не держать постоянно.
  • Не логировать в цикле. Одна запись на пакет из 10 000 элементов, а не 10 000 записей; агрегаты считают в коде.
  • Не дублировать ошибку на каждом слое. Ошибку логирует один слой — error middleware или воркер, — а выше пробрасывает.
  • Сэмплировать шумные успешные запросы. Если access log нужен не для каждого 200, его сэмплируют, а ошибки и медленные запросы пишут всегда.
  • Выносить запись в worker. При высокой нагрузке синхронная запись в stdout становится узким местом: pino.transport() выносит её в worker-поток, а асинхронный destination убирает синхронную блокировку. Плата — риск потерять последние записи при жёстком падении, поэтому перед завершением нужен flush.

Отдельно про формат: JSON в проде удобнее «красивого» вывода. pino-pretty — инструмент разработчика, а не продакшн-пайплайна: он тратит CPU на форматирование и превращает структуру обратно в текст, который придётся парсить.


Health checks: liveness и readiness

Оркестратору и балансировщику нужны два разных ответа, и путать их дорого:

ПроверкаВопросЧто делает при провалеЧто проверять
LivenessПроцесс жив и не завис?Перезапускает контейнерСам процесс, без внешних зависимостей
ReadinessГотов принимать трафик?Убирает из балансировки, не убиваетБаза, Redis, миграции, режим остановки
StartupПриложение уже поднялось?Даёт время на инициализацию, пока liveness не активнаИнициализация, прогрев

Liveness не должна ходить в базу. Если база недоступна пять секунд, все инстансы одновременно провалят liveness, оркестратор перезапустит их, и вместо короткой деградации получится полная авария с холодным стартом. Liveness проверяет то, что может сломаться только в самом процессе: Event Loop отвечает, HTTP-сервер принимает соединения.

Readiness, наоборот, обязана учитывать зависимости — но дешёво и с таймаутом:

// src/routes/health.js
import { Router } from 'express';

export const healthRouter = Router();

let draining = false;
let cached = { at: 0, ok: false };

export function startDraining() {
  draining = true;
}

async function dependenciesOk() {
  if (Date.now() - cached.at < 2000) return cached.ok;

  try {
    await withTimeout(Promise.all([
      pool.query('select 1'),
      redis.ping(),
    ]), 500);
    cached = { at: Date.now(), ok: true };
  } catch {
    cached = { at: Date.now(), ok: false };
  }

  return cached.ok;
}

healthRouter.get('/live', (req, res) => {
  res.json({ status: 'ok' });
});

healthRouter.get('/ready', async (req, res) => {
  if (draining) {
    return res.status(503).json({ status: 'draining' });
  }

  if (!(await dependenciesOk())) {
    return res.status(503).json({ status: 'dependency_down' });
  }

  res.json({ status: 'ready' });
});
function withTimeout(promise, ms) {
  let timer;

  const timeout = new Promise((_, reject) => {
    timer = setTimeout(() => reject(new Error('timeout')), ms);
  });

  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

Здесь важны три детали:

  • Таймаут. Проверка без ограничения сама станет источником зависших запросов. 300–500 мс достаточно: если база не ответила за это время, инстанс всё равно не обслужит запрос нормально. Таймаут не отменяет сам запрос к базе, поэтому у драйвера дополнительно выставляют statement_timeout или connectionTimeoutMillis.
  • Кеш. Балансировщик дергает readiness каждые несколько секунд с каждого инстанса; без кеша проверка превращается в лишнюю нагрузку на базу.
  • Флаг draining. Он переключается до закрытия сервера, чтобы балансировщик успел убрать инстанс из ротации.

Ответ health-эндпоинта не должен содержать внутренние детали: имена хостов, тексты ошибок драйвера и версии. Достаточно status и, если нужно, короткого кода причины — подробности идут в лог.

Порядок остановки: получить SIGTERM → выставить draining → подождать, пока readiness перестанет возвращать 200 и балансировщик исключит инстанс → server.close() и дождаться текущих запросов → закрыть пулы и воркеры → выйти. Если пропустить первый шаг, часть запросов придёт в уже закрывающийся сервер и получит обрыв. Сам graceful shutdown по шагам разбирается в статье «Таймауты, ретраи и graceful shutdown»; health checks здесь — его входная точка.


Метрики: RED и USE

Метрики — агрегаты, которые хранят числа, а не события. В Prometheus-совместимом стеке это счётчики (counter), гистограммы (histogram) и текущие значения (gauge). В Node их собирает prom-client:

// src/lib/metrics.js
import { Registry, collectDefaultMetrics, Counter, Histogram } from 'prom-client';

export const registry = new Registry();
collectDefaultMetrics({ register: registry });

export const httpRequests = new Counter({
  name: 'http_requests_total',
  help: 'HTTP requests by route and status',
  labelNames: ['method', 'route', 'status'],
  registers: [registry],
});

export const httpDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'HTTP request duration',
  labelNames: ['method', 'route', 'status'],
  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

collectDefaultMetrics() уже отдаёт heap, GC, число активных handles и event loop lag. Последняя метрика особенно полезна: рост nodejs_eventloop_lag_p99_seconds означает, что процесс занят синхронной работой и не успевает обслуживать таймеры и I/O — подробнее в статье «Event Loop в Node.js».

RED

Модель RED описывает запросы:

  • Rate — сколько запросов в секунду.
  • Errors — какая доля завершилась ошибкой.
  • Duration — сколько длится запрос, обычно в перцентилях.

Счётчик и гистограмма на каждый маршрут:

app.use((req, res, next) => {
  const stop = httpDuration.startTimer({ method: req.method });

  res.on('finish', () => {
    const route = req.route?.path ? `${req.baseUrl}${req.route.path}` : 'unmatched';
    const labels = {
      method: req.method,
      route,
      status: String(res.statusCode),
    };

    httpRequests.inc(labels);
    stop(labels);
  });

  next();
});

Ключевое здесь — req.route.path, а не req.originalUrl. Шаблон /tasks/:id даёт один временной ряд на маршрут, а сырой URL — по ряду на каждый id. Это и есть взрыв кардинальности: несколько миллионов уникальных значений в метке кладут хранилище и делают запросы по метрике невыполнимо дорогими.

По той же причине в метки не кладут userId, requestId, e-mail, текст ошибки и произвольные query-параметры. Если разрез по пользователю действительно нужен, его выносят в лог или трейс, а не в метрику.

Среднее время ответа — плохая метрика: один медленный запрос из ста почти не меняет среднее, но именно он раздражает пользователя. Смотрят p50, p95 и p99, а гистограмму считают в Prometheus через histogram_quantile. Границы бакетов подбирают под SLO: если цель — 300 мс, бакеты должны сгущаться вокруг 300 мс, иначе перцентиль будет грубым.

USE

Модель USE описывает ресурсы:

  • Utilization — насколько ресурс занят (CPU, память, пул соединений).
  • Saturation — есть ли очередь к ресурсу (запросы в ожидании соединения, длина очереди задач).
  • Errors — отказы ресурса (ошибки пула, таймауты диска).

RED отвечает, что чувствуют пользователи. USE объясняет, почему: например, p99 вырос, потому что пул соединений к базе заполнен и запросы стоят в очереди. Без USE алерт «стало медленно» не даёт зацепки, без RED можно оптимизировать ресурс, который не влияет на пользователей.

Эндпоинт /metrics

Метрики отдают отдельным HTTP-сервером на внутреннем интерфейсе или отдельным портом:

import { createServer } from 'node:http';

const metricsServer = createServer(async (req, res) => {
  if (req.url !== '/metrics') {
    res.writeHead(404).end();
    return;
  }

  res.writeHead(200, { 'content-type': registry.contentType });
  res.end(await registry.metrics());
});

metricsServer.listen(9464, '127.0.0.1');

Публичный /metrics — утечка: по именам маршрутов, версиям и нагрузке видно внутреннее устройство сервиса. В Kubernetes порт закрывают network policy, вне кластера — basic auth или отдельная сеть. Скрейпить метрики должен Prometheus-агент, а не браузер пользователя.


Трассировка через OpenTelemetry

Трейс — это дерево спанов: один корневой спан на входящий запрос и дочерние на базу, внешние HTTP-вызовы, очередь и вычисления. Каждый спан хранит имя, длительность, статус и атрибуты, а связь задаётся через trace_id и span_id.

OpenTelemetry подключают до загрузки приложения, иначе инструментация не успеет обернуть модули:

// instrumentation.js
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  serviceName: 'taskflow-api',
  traceExporter: new OTLPTraceExporter(), // адрес берётся из OTEL_EXPORTER_OTLP_ENDPOINT
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
node --import ./instrumentation.js src/server.js

Автоинструментация покрывает http, fetch/undici, Express, pg, Redis и популярные очереди: спаны на входящие запросы и исходящие вызовы появляются без правок прикладного кода. Свои операции добавляют вручную:

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('taskflow');

await tracer.startActiveSpan('tasks.update', async (span) => {
  try {
    span.setAttribute('task.id', taskId);
    return await updateTask({ taskId, patch });
  } catch (err) {
    span.recordException(err);
    span.setStatus({ code: SpanStatusCode.ERROR });
    throw err;
  } finally {
    span.end();
  }
});

Атрибуты спана — это поля для поиска: task.id, project.id, http.route, db.system. Правила те же, что у меток: ограниченный набор и никаких секретов. user.email в атрибутах — такая же утечка, как в логе.

Распространение контекста

Внутри процесса OTel переносит контекст сам, а между сервисами — через заголовок W3C traceparent. HTTP-инструментация делает это автоматически, но для очередей и самописных протоколов контекст внедряют вручную:

import { context, propagation } from '@opentelemetry/api';

const carrier = {};
propagation.inject(context.active(), carrier);

await queue.add('notify', {
  taskId,
  traceparent: carrier.traceparent,
});

На стороне воркера его извлекают и запускают обработку внутри контекста:

const ctx = propagation.extract(context.active(), {
  traceparent: job.data.traceparent,
});

await context.with(ctx, () => handleNotification(job));

Без этого шага трейс обрывается на границе очереди: задача выглядит как отдельный корневой спан, и связать её с запросом пользователя нельзя.

Сэмплирование

Хранить все трейсы при высоком RPS слишком дорого. По умолчанию OTel использует ParentBased(AlwaysOn) — каждый запрос трассируется, а решение родителя наследуется. В проде чаще берут долю (traceIdRatioBased) или переносят решение на коллектор (tail sampling), где можно сохранить все ошибки и медленные трейсы, а успешные — выборочно.

Сэмплирование не должно влиять на корреляцию: trace_id в логах остаётся, даже если трейс не сохранён. Иначе логи перестанут сходиться с трейсами ровно в тот момент, когда идёт разбор инцидента.


Корреляция сигналов

Три сигнала по отдельности дают фрагменты картины. Вместе они работают, когда у них общие идентификаторы:

  • requestId — в каждой записи лога и в заголовке ответа.
  • trace_id / span_id — в логе, метрике (через exemplar) и спане.
  • route, method, status — одинаковые в логах и метриках, чтобы график и записи сходились.

@opentelemetry/instrumentation-pino автоматически добавляет trace_id и span_id в записи pino. Если инструментация не подключена, их достают из активного спана:

import { trace } from '@opentelemetry/api';

const span = trace.getActiveSpan();

logger.info({
  trace_id: span?.spanContext().traceId,
  span_id: span?.spanContext().spanId,
  msg: 'task updated',
});

Типичный путь разбора аварии выглядит так:

  1. Алерт по метрике: доля 5xx на POST /tasks выросла выше порога.
  2. В трейсах находят медленные и упавшие спаны именно этого маршрута.
  3. По trace_id из спана находят все логи запроса — включая ошибку драйвера базы, которую не видно в метрике.
  4. По requestId проверяют, не повторялся ли тот же сценарий у других пользователей.

Если хотя бы один идентификатор не проставлен, шаг выпадает. Поэтому корреляция — это не «добавим потом», а часть контракта логирования: поля фиксируются в одном месте и проверяются тестом.


Алерты и SLO

Метрики существуют не для дашбордов, а для решения «будить дежурного или нет». Хороший алерт обладает четырьмя свойствами: измеряет то, что чувствует пользователь, имеет порог и длительность, указывает на владельца и содержит ссылку на runbook.

Практическая иерархия:

СигналРеакцияПример
СимптомСтраница дежурномуДоля 5xx выше 2% пять минут
Бюджет ошибокСтраница или тикетSLO 99.9%, burn rate превышен
НасыщениеТикетПул соединений занят более 80% в течение часа
ПричинаДашбордCPU 85%, GC-паузы выросли

Алерт на причину («CPU выше 80%») плох тем, что CPU может быть высоким без влияния на пользователей, а может быть низким при полностью недоступном сервисе. Алерт на симптом («пользователи получают ошибки») срабатывает тогда, когда действительно больно.

SLO задаёт целевой уровень: например, 99.9% успешных запросов за 30 дней. Из него считают бюджет ошибок — сколько минут недоступности допустимо. Алерт по burn rate срабатывает, когда бюджет расходуется быстрее нормы, а не когда превышен произвольный порог. Это позволяет не реагировать на каждый единичный всплеск и при этом замечать медленную деградацию.

Что стоит завести с самого начала:

  • доля ошибок и p95/p99 по каждому маршруту;
  • event loop lag и память процесса;
  • ошибки и занятость пула базы;
  • глубина очереди и задержка обработки задач;
  • число рестартов и неудачных readiness-проверок.

Чего стоит избегать: алертов на каждую запись error в логе, порогов без длительности, дашбордов на двадцать графиков без владельца и «мониторинга», который никто не открывал после настройки.


Практика: observability в TaskFlow

Добавим наблюдаемость к TaskFlow из статей «Express и middleware» и «Конфигурация и валидация».

1. Логгер и контекст. src/lib/logger.js из раздела про pino, src/middleware/context.js с AsyncLocalStorage. Middleware подключается до маршрутов и до логгера запросов:

app.use(requestContext);                     // requestId в req.id и ALS
app.use(pinoHttp({ logger, genReqId: (req) => req.id }));
app.use('/health', healthRouter);

2. Health-эндпоинты. /health/live и /health/ready из раздела про health checks. Readiness учитывает draining и кеширует проверку зависимостей на две секунды.

3. Метрики. src/lib/metrics.js с registry, счётчиком и гистограммой; middleware на finish; отдельный сервер на 127.0.0.1:9464. В дашборд выводят http_requests_total, http_request_duration_seconds и nodejs_eventloop_lag_p99_seconds.

4. Трейсинг. instrumentation.js запускается через --import, экспортирует спаны в OTLP-коллектор. Для фоновой задачи notify контекст передаётся через traceparent в данных задачи.

5. Остановка. Обработчик SIGTERM:

process.on('SIGTERM', async () => {
  startDraining();                 // readiness начнёт отдавать 503

  await waitForLoadBalancer(5_000);
  await new Promise((resolve) => server.close(resolve));
  await Promise.all([pool.end(), redis.quit()]);
  await sdk.shutdown();            // дослать оставшиеся спаны
  await new Promise((resolve) => logger.flush(resolve));

  process.exit(0);
});

Что закрыто: у каждого запроса есть requestId и trace_id; ошибки логируются один раз с контекстом; балансировщик видит готовность; метрики дают алерты по симптомам; инстанс уходит из ротации до закрытия сокетов.

Что добавляют в проде: централизованный сбор и retention-политики, дашборды по RED/USE, SLO и бюджет ошибок, алерты с runbook, сэмплирование трейсов на коллекторе, а также проверку redaction в тестах.


Частые ошибки

  • console.log в проде. Нет уровня, полей и контекста; фильтры и алерты построить нельзя.
  • Логирование целого req/res с телом. Токены, cookie и персональные данные попадают в хранилище.
  • Redaction «на глаз». Путь с опечаткой не ломает приложение и не защищает данные; нужен тест.
  • requestId генерируется, но не передаётся дальше. Цепочка рвётся на первом исходящем вызове.
  • enterWith в middleware. Контекст протекает на следующие запросы в том же стеке.
  • Ошибка логируется на каждом слое. Один инцидент даёт десять записей и ложный всплеск в алертах.
  • Проверка базы в liveness. Сбой зависимости превращается в массовый рестарт.
  • Readiness не учитывает остановку. Во время деплоя часть запросов получает 502.
  • Сырой URL или userId в метках. Кардинальность растёт неограниченно, метрики перестают собираться.
  • Среднее время ответа вместо перцентилей. Медленные запросы исчезают в среднем.
  • Публичный /metrics. Внутренняя топология и нагрузка видны снаружи.
  • 100% трейсов без сэмплирования. Стоимость хранения растёт быстрее пользы.
  • Алерт на каждый error в логе. Шум съедает доверие к мониторингу.
  • Health-проверки в access log. Полезные записи тонут в служебных.
  • Нет flush перед выходом. Последние логи и спаны теряются при рестарте.

Ключевые тезисы для интервью

  • Логи, метрики и трейсы отвечают на разные вопросы: что случилось с конкретным запросом, сколько таких событий и где ушло время. console.log даёт текст без уровня и полей, поэтому не годится для фильтрации, алертов и разбора инцидентов.
  • Структурный лог — это JSON с постоянной схемой; pino даёт уровни, сериализаторы, redaction и дочерние логгеры, а mixin или AsyncLocalStorage добавляют requestId в каждую запись без ручной передачи.
  • Контекст запроса переносится через AsyncLocalStorage, но за границей процесса его нужно явно положить в заголовок или сообщение и так же явно извлечь; иначе requestId и traceparent обрываются на первом внешнем вызове.
  • Liveness проверяет только процесс и при провале вызывает рестарт; readiness проверяет готовность принимать трафик и при провале убирает инстанс из балансировки. Зависимости — только в readiness, с таймаутом и кешем.
  • RED измеряет запросы (rate, errors, duration), USE — ресурсы (utilization, saturation, errors); смотрят перцентили, а метки ограничивают шаблоном маршрута, методом и статусом.
  • OpenTelemetry связывает спаны через traceparent; сэмплирование снижает стоимость, но trace_id в логах должен оставаться всегда, иначе корреляция ломается именно во время аварии.
  • Алертят на симптомы и SLO, а причины смотрят на дашбордах; алерт без владельца, runbook и длительности превращается в шум.

Заключение

Наблюдаемость начинается не с дашборда, а с решения, какие вопросы сервис должен уметь отвечать: кто получил ошибку, сколько запросов затронуто, где именно ушло время. Структурные логи и requestId отвечают на первый вопрос, метрики — на второй, трейсы — на третий. Health checks обеспечивают корректную работу оркестратора и балансировщика, а SLO превращает поток чисел в понятное правило «когда будить человека». Стоимость этой системы растёт вместе с объёмом логов и трейсов, поэтому уровень, сэмплирование, redaction и кардинальность меток — не оптимизация на потом, а часть базовой настройки.

Полезные ссылки