Логирование и наблюдаемость
Сервис падает в три часа ночи, и первое, что нужно понять, — что именно сломалось: конкретный запрос, весь инстанс или зависимость. Ответ зависит от того, какие сигналы сервис оставил до аварии. Ниже — как построить эти сигналы в Node: структурные логи, request-id, health checks, метрики и трассы, — и как не утонуть в их объёме.
Содержание
- Три столпа наблюдаемости
- Структурные логи и pino
- request-id и контекст запроса
- Уровни, объём и стоимость
- Health checks: liveness и readiness
- Метрики: RED и USE
- Трассировка через OpenTelemetry
- Корреляция сигналов
- Алерты и SLO
- Практика: observability в TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Три столпа наблюдаемости
Наблюдаемость строят на трёх типах сигналов, и они отвечают на разные вопросы:
| Сигнал | Вопрос | Объём | Что хранят |
|---|---|---|---|
| Логи | Что произошло с этим запросом? | Растёт с числом запросов | События с полями и контекстом |
| Метрики | Сколько таких событий и как они распределены? | Почти не растёт | Агрегаты: счётчики, гистограммы, 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 в общее хранилище.
Уровни
| Уровень | Число | Когда использовать |
|---|---|---|
trace | 10 | Трассировка циклов и ветвлений, почти никогда в проде |
debug | 20 | Диагностика, включается точечно |
info | 30 | Значимые события: старт, миграции, бизнес-операции |
warn | 40 | Ожидаемая деградация: retry, 4xx, медленный запрос |
error | 50 | Ошибка, которую кто-то должен разобрать |
fatal | 60 | Процесс не может продолжать работу |
Уровень — это не «важность текста», а решение о судьбе записи. Если писать 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',
});
Типичный путь разбора аварии выглядит так:
- Алерт по метрике: доля
5xxнаPOST /tasksвыросла выше порога. - В трейсах находят медленные и упавшие спаны именно этого маршрута.
- По
trace_idиз спана находят все логи запроса — включая ошибку драйвера базы, которую не видно в метрике. - По
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 и кардинальность меток — не оптимизация на потом, а часть базовой настройки.
Полезные ссылки
- pino — документация: уровни, сериализаторы, redaction, transports
- pino-http — access log и request-id для HTTP-сервера
- prom-client — метрики Prometheus для Node
- OpenTelemetry JavaScript — SDK, автоинструментация и экспортёры
- W3C Trace Context — формат
traceparentи распространение контекста - Kubernetes: Liveness, Readiness and Startup Probes — различия и настройка проверок
- Google SRE Book: Service Level Objectives — SLO, бюджет ошибок и алерты
- The Twelve-Factor App: Logs — логи как поток событий
- Управление секретами — хранение, ротация и защита
.envот утечек