0Pricing
Node.js Backend Development Bootcamp · Урок

Структурированное ведение журналов с идентификаторами корреляции

Формируйте журналы JSON, пригодные для машинного разбора, и передавайте идентификаторы корреляции через асинхронный контекст для трассировки запросов.

«Структурированное ведение журналов с идентификаторами корреляции» — бесплатный урок Node.js Backend Development Bootcamp на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Node.js Backend Development Bootcamp, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Node.js Backend Development Bootcamp содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Structured Logging

In production, logs are read by machines before humans. A line like console.log('User ' + id + ' failed login') is a free-form string: to find it later you must write brittle regex and you cannot aggregate or filter reliably.

Structured logging emits each log as a JSON object with consistent fields. Log aggregators (Loki, Elasticsearch, Datadog, CloudWatch) index those fields so you can query level="error" AND userId=42 instantly.

  • Free-form: easy to write, painful to query.
  • Structured: one JSON object per line (NDJSON), trivially parseable.

A Minimal JSON Logger

The core idea is small: build a plain object, stamp it with a level and timestamp, and write one JSON string per line to stdout. The runtime or container collects stdout and ships it to your aggregator.

Each log is a single line of valid JSON. This format is called NDJSON (newline-delimited JSON) and every modern log backend understands it.

function log(level, message, fields = {}) {
  const entry = {
    level,
    time: new Date().toISOString(),
    message,
    ...fields,
  };
  process.stdout.write(JSON.stringify(entry) + '\n');
}

log('info', 'server started', { port: 3000 });
log('error', 'login failed', { userId: 42, reason: 'bad_password' });

Use a Real Logger: pino

Hand-rolling works for learning, but production apps use a battle-tested logger. pino is the de-facto choice for Node.js: it is extremely fast because it serializes JSON in a worker-friendly way and writes asynchronously.

  • logger.info(obj, msg) — the first arg is the object of fields, the second is the message string.
  • Levels: trace, debug, info, warn, error, fatal.
  • In production you pipe stdout to pino-pretty only in dev; raw JSON goes to prod.
const pino = require('pino');
const logger = pino({ level: 'info' });

logger.info({ port: 3000 }, 'server started');
logger.error({ userId: 42, reason: 'bad_password' }, 'login failed');

// Child loggers bind fields onto every subsequent log:
const reqLog = logger.child({ requestId: 'abc-123' });
reqLog.info('handling request');

The Problem: Tracing One Request

Under load, hundreds of requests interleave their logs. When user 42 reports an error, you need to see every log line that belongs to their request — across middleware, services, and database calls.

The solution is a correlation ID (also called request ID or trace ID): a unique identifier generated once per request and attached to every log emitted while handling that request.

  • Query correlationId="7f3a..." and the aggregator reconstructs the whole request timeline.
  • If the ID arrives in an incoming header, you can correlate logs across services.

Generating and Accepting the ID

At the edge of your system, read an incoming correlation header if a caller (gateway, upstream service) already set one; otherwise generate a fresh UUID. Always echo it back in the response so clients and proxies can record it too.

Standard header names are x-request-id or x-correlation-id. Reusing an inbound ID is what makes tracing work across service boundaries.

const { randomUUID } = require('crypto');

function correlationMiddleware(req, res, next) {
  const incoming = req.headers['x-correlation-id'];
  const correlationId = incoming || randomUUID();
  req.correlationId = correlationId;
  res.setHeader('x-correlation-id', correlationId);
  next();
}

module.exports = { correlationMiddleware };

The Naive Approach and Its Pain

The obvious move is to pass req.correlationId as an argument into every function and every log call. This works but does not scale: a deep call stack (controller → service → repository → helper) forces you to thread the ID through functions that otherwise have no reason to know about it.

This is prop drilling for the backend. You want the ID available implicitly to any code running during the request — without changing every function signature.

AsyncLocalStorage to the Rescue

Node.js ships AsyncLocalStorage (in the async_hooks module). It creates a store that stays bound to the current asynchronous execution context — surviving across await, callbacks, timers, and promises — without being shared between concurrent requests.

Think of it as request-scoped thread-local storage. You call als.run(store, callback) once per request; anywhere inside that callback (no matter how deep or how many awaits later) als.getStore() returns the same store.

const { AsyncLocalStorage } = require('async_hooks');
const als = new AsyncLocalStorage();

async function deep() {
  await new Promise((r) => setTimeout(r, 10));
  // Same store, even after awaits and timers:
  return als.getStore().correlationId;
}

async function main() {
  await als.run({ correlationId: 'req-1' }, async () => {
    console.log('inside:', await deep());
  });
  console.log('outside:', als.getStore());
}

main();

Wiring AsyncLocalStorage into the Request

Replace the naive middleware: instead of attaching the ID to req, run the rest of the request inside als.run() with the ID in the store. Now every line of code executed for this request — controllers, services, DB callbacks — can reach the ID via getStore().

Crucially, you must call next() inside the run callback so the downstream handlers inherit the context.

const { AsyncLocalStorage } = require('async_hooks');
const { randomUUID } = require('crypto');

const als = new AsyncLocalStorage();

function context() {
  return als.getStore() || {};
}

function correlationMiddleware(req, res, next) {
  const correlationId = req.headers['x-correlation-id'] || randomUUID();
  res.setHeader('x-correlation-id', correlationId);
  als.run({ correlationId }, () => next());
}

module.exports = { als, context, correlationMiddleware };

Auto-Injecting the ID into Every Log

The payoff: wrap your logger so it reads the correlation ID from AsyncLocalStorage automatically. Application code calls log.info('saved order') with no ID argument, yet every emitted line carries the right correlationId.

With pino you express this declaratively using the mixin option, which merges extra fields into every log record at write time.

const pino = require('pino');
const { als } = require('./context');

const logger = pino({
  level: 'info',
  mixin() {
    const store = als.getStore();
    return store ? { correlationId: store.correlationId } : {};
  },
});

// Anywhere deep in the request, no ID passed explicitly:
function saveOrder(order) {
  logger.info({ orderId: order.id }, 'order saved');
}

module.exports = { logger, saveOrder };

Propagating the ID to Downstream Calls

Correlation only spans services if you forward the ID on outbound requests. When your service calls another HTTP API, read the ID from context and set it as a header. The downstream service's middleware will reuse it, so both services' logs share one ID.

The same principle applies to message queues (put the ID in message metadata) and background jobs (store it on the job payload).

const { context } = require('./context');

async function callInventoryService(sku) {
  const { correlationId } = context();
  const res = await fetch('https://inventory.internal/check', {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-correlation-id': correlationId,
    },
    body: JSON.stringify({ sku }),
  });
  return res.json();
}

module.exports = { callInventoryService };

Production Hygiene

A few rules keep your structured logs clean and safe:

  • Never log secrets or PII — passwords, tokens, full card numbers. Configure pino redact paths (e.g. ['req.headers.authorization', '*.password']).
  • Log at the right level — info for business events, warn for recoverable issues, error with the serialized error object for failures.
  • Keep field names stable — correlationId always means the same thing; dashboards and alerts depend on it.
  • One JSON object per line — do not pretty-print in production; it breaks NDJSON parsing.
const pino = require('pino');

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: ['req.headers.authorization', 'password', '*.password', 'creditCard'],
});

logger.info({ user: { id: 7, password: 'hunter2' } }, 'login');
// -> password is replaced with [Redacted] in the output

Quick Check

You need the correlation ID available to every function in a deep call stack during a request, without passing it as an argument and without leaking it between concurrent requests. What is the correct mechanism in Node.js?

Recap

You learned how to make logs both machine-parseable and traceable:

  • Structured logging emits one JSON object per line (NDJSON) so aggregators can index and query fields.
  • pino is the standard fast Node.js logger; the field object comes first, the message second.
  • A correlation ID is generated or reused from an inbound header once per request and echoed in the response.
  • AsyncLocalStorage threads that ID through the whole async call stack without changing function signatures, and isolates concurrent requests.
  • Pino's mixin auto-injects the ID into every log; forwarding it as an outbound header extends tracing across services.
  • Practice good hygiene: redact secrets, use correct levels, keep field names stable, never pretty-print in production.

Часто задаваемые вопросы

Урок «Структурированное ведение журналов с идентификаторами корреляции» бесплатный?

Да — полный текст урока «Структурированное ведение журналов с идентификаторами корреляции» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Node.js Backend Development Bootcamp, подпишись на CoddyKit PRO. Курс Node.js Backend Development Bootcamp содержит 4 уроков всего.

Чему я научусь в уроке «Структурированное ведение журналов с идентификаторами корреляции»?

Формируйте журналы JSON, пригодные для машинного разбора, и передавайте идентификаторы корреляции через асинхронный контекст для трассировки запросов. Ты практикуешь Node.js Backend Development Bootcamp с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Node.js Backend Development Bootcamp?

Предыдущий опыт не требуется. Node.js Backend Development Bootcamp на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Структурированное ведение журналов с идентификаторами корреляции»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Node.js Backend Development Bootcamp?

Да. Каждый урок Node.js Backend Development Bootcamp включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Структурированное ведение журналов с идентификаторами корреляции
  2. Распределённая трассировка с интервалами OpenTelemetry
  3. Предоставление метрик приложения и метод RED
  4. Передача контекста с AsyncLocalStorage
← Назад к Node.js Backend Development Bootcamp