4.7. Логирование

Для ведения логов в платформе используется фреймворк Logback.

Руководство Logging in CUBA Applications показывает, как ведение логов интегрируется, настраивается и просматривается в виде части самого приложения или с помощью внешних инструментов.

Для вывода в лог используйте SLF4J API, получая логгер по имени текущего класса. Пример создания логгера и вывода в него:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Foo {
    // create logger
    private static Logger log = LoggerFactory.getLogger(Foo.class);

    private void someMethod() {
        // output message with DEBUG level
        log.debug("invoked someMethod");
    }
}
Конфигурация логирования

Конфигурация логирования задается в файле logback.xml.

  • На этапе разработки, данный файл можно найти в каталоге deploy/app_home проекта после выполнения быстрого развертывания. Файлы логов создаются в каталоге deploy/app_home/logs.

    Имейте в виду, что каталог deploy не внесен в Git, и может быть удален и пересоздан в любой момент, поэтому изменения, внесенные в файлы этого каталога могут быть легко потеряны.

    Если вы хотите внести постоянные изменения в конфигурацию логирования, используемую при разработке, создайте файл etc/logback.xml (его можно скопировать из исходного deploy/app_home/logback.xml и изменить как требуется). Этот файл будет копироваться в deploy/app_home каждый раз, когда вы запускаете приложение в Studio или выполняете задачу Gradle deploy:

    my_project/
    deploy/
        app_home/
            logback.xml
    ...
    etc/
        logback.xml - if exists, will be automatically copied to deploy/app_home

  • При создании архивов WAR и UberJAR, logback.xml можно предоставить с помощью указания относительного пути к нужному файлу в параметре logbackConfigurationFile задач buildWar и buildUberJar. Если данный параметр не указан, в WAR/UberJar будет встроена конфигурация логирования по умолчанию.

    Имейте в виду, что файл etc/logback.xml, созданный вами для конфигурации этапа разработки, не будет использован по умолчанию для WAR/UberJar, т.е. необходимо указать файл явно:

    my_project/
    etc/
        logback.xml
        war-logback.xml
    build.gradle 
    task buildWar(type: CubaWarBuilding) {
    // ...
    logbackConfigurationFile = 'etc/war-logback.xml'
}

  • На этапе эксплуатации встроенную в WAR/UberJAR конфигурацию логирования можно переопределить, положив файл logback.xml с нужными настройками в домашний каталог приложения.

    Файл logback.xml в домашнем каталоге приложения будет распознан только если системное свойство app.home указано в командной строке. Это не сработает, если домашний каталог будет установлен автоматически в tomcat/work/app_home или ~/.app_home.
logback.xml structure

Рассмотрим структуру файла logback.xml.

  • Элементы appender задают "устройства вывода" логов. Основными аппендерами являются FILE и CONSOLE. В параметре level элемента filter можно задать порог уровня сообщения. По умолчанию порог для файла - DEBUG, для консоли - INFO. Это означает, что в файл выводятся сообщения с уровнями ERROR, WARN, INFO, DEBUG, а в консоль - с уровнями ERROR, WARN и INFO.

    Для файлового аппендера в элементе file задается путь к файлу лога.

  • Элементы logger задают параметры логгеров, через которые производится посылка сообщений из кода программы. Имена логгеров иерархические, то есть например настройки для логгера com.company.sample влияют на логгеры com.company.sample.core.CustomerServiceBean, com.company.sample.web.CustomerBrowse, если для них явно не заданы собственные настройки.

    Минимальный уровень указывается в атрибуте level. Например, если для логгера задан приоритет INFO, то сообщения с уровнями DEBUG и TRACE выводиться не будут. Следует иметь в виду, что на вывод сообщения также влияет порог уровня, заданный в аппендере.

Оперативно изменять уровни для логгеров и пороги аппендеров для работающего сервера можно с помощью экрана Administration > Server Log, доступного в веб-клиенте. Сделанные настройки логирования действуют только в текущем сеансе работы сервера и в файл не сохраняются. Этот экран позволяет также просматривать и загружать файлы логов из каталога журналов сервера.

Log message format

Платформа автоматически добавляет к сообщениям, выводимым в лог, следующую информацию:

  • приложение - имя веб приложения, развернутого в Tomcat, код которого выводит данное сообщение. Эта информация помогает различить сообщения от разных блоков приложения (Middleware, Web Client), так как они выводятся в один файл.

  • пользователь - логин пользователя приложения, от имени которого в данный момент работает код, выводящий сообщение. Это позволяет в общем логе отслеживать активность конкретных пользователей. Если код, выводящий сообщение, не связан в момент вывода с пользовательской сессией, информация о пользователе не выводится.

Например, следующее сообщение в логе выведено кодом блока Middleware (app-core), работающим от имени пользователя admin:

16:12:20.498 DEBUG [http-nio-8080-exec-7/app-core/admin] com.haulmont.cuba.core.app.DataManagerBean - loadList: ...