Настройка логирования

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

Включение логирования

По умолчанию Unpoly работает с минимальным уровнем логирования, выводя только критические ошибки. Для активации расширенного логирования используется свойство up.log:

up.log = true;

Это включает вывод всех сообщений в консоль браузера. Сообщения включают:

  • инициируемые события (up:click, up:fragment:loaded),
  • отправку и получение AJAX-запросов,
  • обновление фрагментов DOM,
  • ошибки при обработке скриптов и шаблонов.

Для более тонкой настройки можно использовать уровни логирования:

up.log = {
  enabled: true,
  level: 'debug' // доступные уровни: 'debug', 'info', 'warn', 'error'
};
  • debug — максимально подробный вывод, полезен при разработке сложной интерактивности.
  • info — вывод основных событий и действий Unpoly.
  • warn — предупреждения, связанные с некорректным использованием API.
  • error — только критические ошибки, влияющие на работу фреймворка.

Настройка форматирования сообщений

Unpoly позволяет кастомизировать формат сообщений, подключая собственный обработчик через up.log.handler:

up.log.handler = function(level, message, context) {
  console.log(`[${level.toUpperCase()}] ${message}`, context);
};
  • level — уровень сообщения (debug, info, warn, error).
  • message — текст сообщения.
  • context — объект с дополнительными данными (например, элемент DOM или объект запроса).

Этот подход позволяет интегрировать логирование с внешними системами аналитики или кастомными консольными форматами.

Фильтрация сообщений

Для удобства работы с большим количеством сообщений можно использовать фильтры по типу события или по элементу:

up.log.filter = function(level, message, context) {
  return context && context.fragment && context.fragment.id === 'main';
};

В данном примере выводятся только сообщения, относящиеся к фрагменту с идентификатором main. Аналогично можно фильтровать события по URL, типу запроса или другим критериям.

Логирование AJAX-запросов

Unpoly тесно интегрирован с AJAX, поэтому отслеживание запросов — важная часть отладки. Для логирования запросов используется событие up:request:

up.on('up:request', function(event) {
  console.debug('AJAX запрос:', event.request.url, 'Метод:', event.request.method);
});

Также можно отслеживать успешное завершение и ошибки запросов:

up.on('up:request:load', function(event) {
  console.info('Ответ получен:', event.request.responseText);
});

up.on('up:request:error', function(event) {
  console.error('Ошибка запроса:', event.request.status, event.request.statusText);
});

Эта детализация позволяет выявлять проблемы с загрузкой фрагментов и неправильной обработкой данных на клиенте.

Динамическое включение и отключение логирования

Иногда необходимо включать логирование только в определённых сценариях или при обнаружении ошибок. Это возможно с помощью изменения свойства up.log.enabled в рантайме:

if (window.location.search.includes('debug')) {
  up.log.enabled = true;
} else {
  up.log.enabled = false;
}

Такой подход минимизирует нагрузку на консоль в продакшене и сохраняет производительность.

Логирование событий фрагментов

Unpoly оперирует фрагментами DOM, и отслеживание их обновления важно для диагностики UI. Для этого используются события up:fragment:loading, up:fragment:loaded, up:fragment:removed:

up.on('up:fragment:loaded', function(event) {
  console.log('Фрагмент загружен:', event.fragment);
});

Контекст события содержит информацию о DOM-элементе, URL запроса и статусе загрузки, что позволяет анализировать последовательность обновлений и выявлять узкие места.

Интеграция с внешними системами логирования

С помощью кастомного обработчика сообщений up.log.handler можно интегрировать Unpoly с такими системами, как Sentry, LogRocket или собственными серверными логами. Пример отправки ошибок на сервер:

up.log.handler = function(level, message, context) {
  if (level === 'error') {
    fetch('/log', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({level, message, context})
    });
  }
};

Это обеспечивает централизованное отслеживание ошибок и облегчает анализ проблем в приложении.

Практические рекомендации

  • Использовать debug только на стадии разработки и тестирования.
  • В продакшене ограничиваться уровнями warn и error.
  • Кастомные обработчики полезны для интеграции с корпоративными системами логирования.
  • Фильтры сообщений помогают уменьшить шум в консоли и сосредоточиться на критических событиях.

Настройка логирования в Unpoly позволяет получать детальную информацию о работе фреймворка, контролировать процесс загрузки фрагментов, анализировать AJAX-запросы и выявлять ошибки на раннем этапе. Гибкость и настраиваемость делают логирование инструментом не только для отладки, но и для мониторинга поведения сложных интерфейсов.

Оглавление