Структуроване логування

Додайте JSON-логи, кореляційні ідентифікатори та контекст запитів для ефективного пошуку подій у системах збору логів.

Що таке структуроване логування

Звичайний текстовий лог зручний для читання людиною:

text

2026-08-19T10:15:22.341Z Request completed in 42 ms

Але системам збору логів складно надійно витягнути з такого повідомлення HTTP-метод, статус, ідентифікатор користувача або тривалість запиту.

Структурований лог — це запис зі стабільною структурою, найчастіше JSON:

json

javascript

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

const requestContext = new AsyncLocalStorage();

function getRequestId(request) {
  const header = request.headers['x-request-id'];
  const value = Array.isArray(header) ? header[0] : header;

  // Приймаємо лише короткі ідентифікатори з безпечними символами.
  if (typeof value === 'string' && /^[a-zA-Z0-9._-]{1,128}$/.test(value)) {
    return value;
  }

  return randomUUID();
}

function serializeError(error) {
  if (!(error instanceof Error)) {
    return { value: String(error) };
  }

  return {
    name: error.name,
    message: error.message,
    stack: error.stack
  };
}

function log(level, message, fields = {}) {
  const context = requestContext.getStore() || {};

  const entry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    ...context,
    ...fields
  };

  process.stdout.write(`${JSON.stringify(entry)}\n`);
}

const logger = {
  debug(message, fields) {
    log('debug', message, fields);
  },

  info(message, fields) {
    log('info', message, fields);
  },

  warn(message, fields) {
    log('warn', message, fields);
  },

  error(message, fields) {
    log('error', message, fields);
  }
};

function delay(milliseconds) {
  return new Promise((resolve) => {
    setTimeout(resolve, milliseconds);
  });
}

async function handleRequest(request, response) {
  const url = new URL(
    request.url,
    `http://${request.headers.host || 'localhost'}`
  );

  if (url.pathname === '/fail') {
    await delay(20);
    throw new Error('Демонстраційна помилка');
  }

  if (url.pathname === '/hello') {
    await delay(30);

    logger.info('Business operation completed', {
      operation: 'hello'
    });

    response.statusCode = 200;
    response.setHeader('content-type', 'application/json; charset=utf-8');
    response.end(JSON.stringify({ message: 'Привіт!' }));
    return;
  }

  response.statusCode = 404;
  response.setHeader('content-type', 'application/json; charset=utf-8');
  response.end(JSON.stringify({ error: 'Not found' }));
}

const server = http.createServer((request, response) => {
  const requestId = getRequestId(request);
  const startedAt = Date.now();

  response.setHeader('x-request-id', requestId);

  requestContext.run(
    {
      requestId
    },
    async () => {
      const url = new URL(
        request.url,
        `http://${request.headers.host || 'localhost'}`
      );

      logger.info('Request started', {
        method: request.method,
        path: url.pathname
      });

      try {
        await handleRequest(request, response);
      } catch (error) {
        response.statusCode = 500;
        response.setHeader('content-type', 'application/json; charset=utf-8');
        response.end(JSON.stringify({ error: 'Internal Server Error' }));

        logger.error('Request failed', {
          error: serializeError(error)
        });
      } finally {
        logger.info('Request completed', {
          method: request.method,
          path: url.pathname,
          statusCode: response.statusCode,
          durationMs: Date.now() - startedAt
        });
      }
    }
  );
});

server.listen(3000, () => {
  logger.info('Server started', {
    port: 3000
  });
});

json

{"timestamp":"...","level":"info","message":"Request started","requestId":"checkout-123","method":"GET","path":"/hello"}
{"timestamp":"...","level":"info","message":"Business operation completed","requestId":"checkout-123","operation":"hello"}
{"timestamp":"...","level":"info","message":"Request completed","requestId":"checkout-123","method":"GET","path":"/hello","statusCode":200,"durationMs":31}

Структуроване логування

Що таке структуроване логування

Які поля варто логувати

Рівні логування

Кореляційний ідентифікатор

Контекст запиту в Node.js

Приклад JSON-логера з контекстом

Логування помилок

Що не можна записувати в логи

Пошук подій за кореляційним ідентифікатором

Типові помилки

Змішування текстових і JSON-логів

Унікальний ідентифікатор лише для частини подій

Глобальна змінна для поточного запиту

Логування всього об’єкта помилки або запиту

Нестабільні назви полів

Підсумок