Логирование запросов с помощью middleware в Node.js

Когда что-то ломается в вашем API в 2 часа ночи, первое, к чему вы обращаетесь — это логи. Если они отсутствуют, неполные или утонули в шуме, отладка превращается в угадывание. Логирование HTTP-запросов в Node.js — одна из тех основ, которую легко сделать неправильно и дорого игнорировать.

В этой статье рассматривается, как работает middleware для логирования запросов в Express, когда использовать проверенные библиотеки вроде Morgan или Pino, и как выглядит production-ready логирование на практике.

Как middleware для логирования вписывается в жизненный цикл запроса Express

В Express middleware — это функция с сигнатурой (req, res, next). Она перехватывает каждый запрос до того, как он достигнет вашего обработчика маршрута. Middleware для логирования находится в начале этой цепочки, записывая, что пришло и что ушло.

[Клиент] → [Logging Middleware] → [Auth Middleware] → [Обработчик маршрута] → [Ответ]

Ключевой момент: вы не можете залогировать полный ответ — код статуса, длительность — пока ответ не завершён. Вот почему middleware для логирования слушает событие finish объекта res, а не логирует немедленно.

import crypto from 'node:crypto'

// Express middleware для логирования запросов
const logRequests = (req, res, next) => {
  const start = Date.now()

  res.on('finish', () => {
    logger.info({
      method: req.method,
      url: req.url,
      status: res.statusCode,
      duration: Date.now() - start,
      requestId: req.headers['x-request-id'] ?? crypto.randomUUID(),
    })
  })

  next()
}

app.use(logRequests)

Обратите внимание, что crypto.randomUUID() требует импорта модуля node:crypto (или использования глобального crypto, доступного в Node.js 19+). Также объект logger здесь является заполнителем — вы должны заменить его на экземпляр вашей реальной библиотеки логирования (например, Pino или console).

Этот паттерн работает с любым HTTP-сервером Node.js, не только с Express.

Традиционное логирование доступа с Morgan

Morgan — классическое middleware для логирования запросов в Express. Две строки — и у вас есть логи доступа в стиле Apache:

import morgan from 'morgan'

app.use(morgan('combined'))
// Пример вывода:
// ::1 - - [01/Jan/2025:00:00:00 +0000] "GET /api/users HTTP/1.1" 200 1234

Morgan подходит для разработки и простых развёртываний. Его вывод читаем человеком, но не легко парсится машиной — что становится проблемой, когда вы отправляете логи в Datadog, Loki или любую систему структурированных логов.

Структурированное логирование в Node.js с Pino

Для production структурированное логирование означает вывод в JSON. Каждая строка лога становится записью, по которой можно делать запросы. Pino — стандартный выбор здесь — он значительно быстрее Winston или Bunyan, с минимальными накладными расходами.

Пакет pino-http встраивается как middleware для Express:

import express from 'express'
import pinoHttp from 'pino-http'

const app = express()

app.use(pinoHttp({
  level: process.env.LOG_LEVEL ?? 'info',
  redact: ['req.headers.authorization', 'req.headers.cookie'],
}))

app.get('/', (req, res) => {
  req.log.info('handling root request')
  res.send('ok')
})

Pino пишет в stdout. Ваша инфраструктура (Docker, systemd, log shipper) обрабатывает маршрутизацию этих строк туда, куда им нужно попасть.

Correlation ID и контекст запроса

Когда вы отслеживаете запрос через множество асинхронных операций, вам нужен согласованный ID запроса, прикреплённый к каждой строке лога. В современном Node.js используйте для этого AsyncLocalStorage — не устаревший модуль domain или низкоуровневые async hooks.

import { AsyncLocalStorage } from 'node:async_hooks'
import crypto from 'node:crypto'

export const requestContext = new AsyncLocalStorage()

app.use((req, res, next) => {
  const requestId = req.headers['x-request-id'] ?? crypto.randomUUID()
  requestContext.run({ requestId }, next)
})

Любой вызов логгера внутри асинхронного контекста этого запроса теперь может получить requestId без необходимости вручную передавать его через каждую функцию. Вот как вы можете его получить:

// В любом downstream-модуле
import { requestContext } from './context.js'

function doWork() {
  const { requestId } = requestContext.getStore()
  logger.info({ requestId, msg: 'doing work' })
}

Ответственное логирование

Несколько правил, которые важны в production:

• Никогда не логируйте заголовки Authorization, cookies или API-токены. Используйте опцию redact в Pino или выполняйте санитизацию вручную перед записью.
• Будьте осторожны с IP-адресами клиентов за прокси. req.socket.remoteAddress даст вам IP прокси. Если ваше приложение находится за обратным прокси, правильно настройте параметр trust proxy в Express и осторожно обрабатывайте заголовки X-Forwarded-For.
• Не логируйте тела запросов по умолчанию. Они могут быть большими, бинарными или содержать персональные данные. Логируйте их выборочно, с ограничениями по размеру.

Выбор между Morgan и Pino

Используйте Morgan для локальной разработки, если предпочитаете читаемый вывод. Используйте Pino для всего, что отправляется в production.

Заключение

Хорошее middleware для логирования незаметно, пока оно вам не понадобится — и тогда оно становится всем. Начните с pino-http, выводите структурированный JSON в stdout и позвольте вашей инфраструктуре обрабатывать маршрутизацию и хранение. Объедините это с correlation ID через AsyncLocalStorage, чтобы вы могли отследить любой запрос от начала до конца. Держите чувствительные данные вне ваших логов с первого дня, и у вас будет фундамент observability, который масштабируется вместе с вашим приложением.

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

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.