Elysia BunnyLogger

Высокопроизводительный, типобезопасный плагин логирования для Elysia, основанный на BunnyLogger.

🌟 Особенности

• Типобезопасное логирование — полная поддержка TypeScript с дженериками
• Цветное форматирование — визуально различимые HTTP методы и статусы
• Трассировка запросов — уникальные идентификаторы для каждого запроса
• Измерение производительности — автоматическое определение медленных запросов
• Безопасность — фильтрация чувствительных данных
• Гибкая настройка — логирование заголовков, тела запроса и ответа
• Контекстное логирование — расширенная информация о запросах

📦 Установка

# Используя npm
npm install @onreza/bunny-logger-elysia

# Используя yarn
yarn add @onreza/bunny-logger-elysia

# Используя bun
bun add @onreza/bunny-logger-elysia

Убедитесь, что у вас также установлен пакет BunnyLogger:

bun add @onreza/bunny-logger

🚀 Быстрый старт

import { Elysia } from 'elysia';
import { bunnyLogger } from '@onreza/bunny-logger-elysia';

const app = new Elysia()
  // Добавляем плагин логирования с настройками по умолчанию
  .use(bunnyLogger())

  // Доступ к логгеру через ctx
  .get('/', ({ logger }) => {
    logger.info('Обрабатываем запрос главной страницы');
    return 'Hello World!';
  })

  .listen(3000);

console.log(`🦊 Сервер запущен на http://localhost:3000`);

⚙️ Настройка

import { Elysia } from 'elysia';
import { bunnyLogger } from '@onreza/bunny-logger-elysia';
import { BunnyLogger } from '@onreza/bunny-logger';

// Настраиваем собственный логгер
const logger = new BunnyLogger({
  name: 'my-api',
  level: 'debug',
  prettify: true,
  style: 'fancy',
  theme: 'pastel'
});

const app = new Elysia()
  .use(bunnyLogger({
    // Используем свой логгер
    logger,

    // Уровень для успешных запросов
    logLevel: 'info',

    // Медленные запросы (в миллисекундах)
    slowRequestThreshold: 300,

    // Игнорируем определенные маршруты
    ignorePaths: ['/health', '/metrics', /\/assets\/.*/],

    // Показывать информацию о запуске сервера
    showServerStartMessage: true,

    // Логируем только определенные HTTP методы
    methods: ['GET', 'POST', 'PUT', 'DELETE'],

    // Настройка идентификаторов запросов
    requestIdHeader: 'x-request-id',
    generateRequestId: true,

    // Логирование данных запроса и ответа
    logRequestBody: true,
    logRequestHeaders: true,
    logResponseBody: true,

    // Маскирование чувствительных данных
    sensitiveKeys: ['password', 'token', 'apiKey', 'credit_card'],

    // Дополнительный контекст
    logContext: {
      service: 'user-api',
      version: '1.0.0'
    },

    // Максимальный размер логируемых тел запросов
    bodyMaxSize: 4096 // 4 KB
  }))

  .get('/', () => 'Hello World!')

  .listen(3000);

🧩 Типизированные метаданные

// Определяем тип метаданных для запросов
interface UserApiContext {
  tenantId: string;
  service: 'auth' | 'users' | 'billing';
  environment: string;
}

// Создаем логгер с собственными метаданными
const logger = new BunnyLogger<UserApiContext>({
  name: 'user-api',
  metadata: {
    tenantId: 'main',
    service: 'users',
    environment: process.env.NODE_ENV || 'development'
  }
});

const app = new Elysia()
  // Используем типизированный логгер в плагине
  .use(bunnyLogger<UserApiContext>({
    logger,
    logRequestBody: true
  }))

  .get('/users/:id', ({ logger, params }) => {
    // Логгер доступен с заданными метаданными
    logger.info(`Запрос пользователя с ID ${params.id}`);
    return { id: params.id, name: 'John Doe' };
  });

📊 Примеры использования

Логирование бизнес-логики

// Расширяем контекст запроса
interface RequestContext {
  requestId: string;
  userId?: string;
  action?: string;
}

app.use(bunnyLogger<RequestContext>())
  .post('/login', async ({ body, logger, set }) => {
    // Добавляем пользовательский контекст к запросу
    const requestLogger = logger.with({
      action: 'user.login',
      userEmail: body.email
    });

    try {
      // Логируем действие пользователя
      requestLogger.info('Попытка входа пользователя');

      // Бизнес-логика авторизации
      const user = await authService.login(body.email, body.password);

      if (user) {
        requestLogger.info('Успешный вход пользователя', { userId: user.id });
        return { success: true, token: generateToken(user) };
      } else {
        requestLogger.warn('Неудачная попытка входа', { reason: 'invalid_credentials' });
        set.status = 401;
        return { success: false, error: 'Неверные учетные данные' };
      }
    } catch (error) {
      requestLogger.error('Ошибка при авторизации', error);
      set.status = 500;
      return { success: false, error: 'Внутренняя ошибка сервера' };
    }
  });

Мониторинг API

import { BannerManager } from '@onreza/bunny-logger';

// Инициализируем баннер для мониторинга
BannerManager.init({
  active: true,
  updateIntervalMs: 1000
});

// Добавляем статистику запросов
let requestCount = 0;
let errorCount = 0;

BannerManager.addStatusItem('Запросы', () => `${requestCount}`);
BannerManager.addStatusItem('Ошибки', () => `${errorCount}`);
BannerManager.addStatusItem('Ошибки %', () =>
  requestCount > 0 ? `${((errorCount / requestCount) * 100).toFixed(2)}%` : '0%'
);

// Настраиваем логгер для сбора статистики
app.use(bunnyLogger({
  logger: new BunnyLogger({ name: 'api-stats' }),
  onRequest: () => {
    requestCount++;
  },
  onError: () => {
    errorCount++;
  }
}));

📖 API Reference

Опции bunnyLogger()

| Опция | Тип | По умолчанию | Описание | |-------|-----|--------------|----------| | logger | BunnyLogger<T> | new BunnyLogger({ name: 'elysia' }) | Экземпляр логгера | | logLevel | 'debug' \| 'info' \| 'warn' \| 'error' | 'info' | Уровень для успешных запросов | | slowRequestThreshold | number | 500 | Порог для медленных запросов (мс) | | ignorePaths | (string \| RegExp)[] | [] | Маршруты для игнорирования | | showServerStartMessage | boolean | true | Вывод информации о запуске | | methods | string[] | ['GET', 'POST', ...] | HTTP методы для логирования | | requestIdHeader | string | 'x-request-id' | Заголовок для ID запроса | | generateRequestId | boolean | true | Генерация ID для запросов | | logRequestBody | boolean | false | Логирование тела запроса | | logRequestHeaders | boolean | false | Логирование заголовков | | logResponseBody | boolean | false | Логирование тела ответа | | sensitiveKeys | string[] | [] | Чувствительные данные для маскирования | | logContext | Record<string, any> | {} | Дополнительный контекст | | bodyMaxSize | number | 10240 | Максимальный размер тела (байт) |

Структура логов запросов

Для каждого запроса логгер создает несколько записей:

1. Начало запроса: → METHOD /path

   [2023-10-14T12:34:56.789Z] [elysia] [DEBUG] → GET /users/123

2. Успешное завершение: ← METHOD /path ✅ 200 [10ms]

   [2023-10-14T12:34:56.799Z] [elysia] [INFO] ← GET /users/123 ✅ 200 [10ms]

3. Ошибка: ← METHOD /path 💥 500 [15ms] Error message

   [2023-10-14T12:34:56.804Z] [elysia] [ERROR] ← POST /users/create 💥 400 [15ms] Missing required fields

🔍 Отладка

Для просмотра дополнительной информации о запросах установите уровень логирования в debug:

app.use(bunnyLogger({
  logger: new BunnyLogger({
    name: 'elysia',
    level: 'debug'
  })
}));

📄 Лицензия

MIT