     
Руководство пользователя по технологии централизованного журналирования по пользователю.
2013. Diasoft Co. Все права защищены.
Содержание
Содержание 5
1.Введение 6
2. Настройка стенда 7
2.1.Конфигурационный файл common-config.xml 7
2.2.Хранение данных 8
2.2.1.Инициализация БД 8
2.3.Настройка log4j 9
2.3.1.Настройка log4j через log4j.xml 9
2.3.2.Настройка log4j через log4j.properties 11
3. Настройка журналирования через визуальный интерфейс 12
4.Просмотр журналируемых данных 13
5.Подключение библиотеки журналирования к сервису 14
1.Введение
Технология централизованного журналирования по пользователю позволяет:
Настроить уровни журналирования без перезагрузки сервиса(сервисов).
Настроить уровни журналирования по конкретному пользователю.
Настроить уровни журналирования через визуальный интерфейс в модуле ”Администратор”
Централизованно хранить всю журналируемую информацию в отдельной SQL базе данных.
Просмотреть и отфильтровать по параметрам (дата, логин пользователя, идентификатор выполняемого метода и др.) журналируемые данные через визуальный интерфейс в модуле ”Администратор”
Данная технология значительно упрощает отладку и выявление ошибок в следующих ситуациях:
одновременно происходит большое количество запросов к методам сервиса
доступ к журналам затруднен, журналирования информацию “разбросана” по большому количеству файлов
текущий уровень журналирования сервиса выставлен в минимальные значения и сервис нельзя перезапустить
необходимо сохранить высокую производительность сервиса при отладке
Полезен в случае, когда сервис установлен в промышленную эксплуатацию, на общий тестовый стенд или работает в кластере.
2. Настройка стенда
2.1.Конфигурационный файл common-config.xml
В конфигурационный файл common-config.xml необходимо добавить следующие настройки:
Настройка userLoggerEnabled.
userLoggerEnabled = 0
Прекратить журналирование по пользователю и не производить опрос сервиса adminWs.
userLoggerEnabled = 1
Начать журналирование по пользователю и проивзодить опрос сервиса adminWs.
< userLoggerEnabled>1
Данная, настройка каждый раз считывается с диска и не кэшируется.
Добавить логин и пароль пользователя с типом «Программный продукт»
логин для доступа к adminws -->
program
пароль -->
12345678fla
Также можно задать два необязательных параметра
1
1 -->
1
Пример конфигурации:
1
program
12345678
1
1
2.2.Хранение данных
По умолчанию, журналируемая информация пишется в директорию %CONFIG_DIR%\logs в файлы вида %loginName%.log, где CONFIG_DIR директория, где лежат конфигурационные файлы (*-config.xml), loginName – логин пользователя.
Вывод информации можно переопределить, настроив свой log4j аппендер (appender) или сразу несколько аппендеров. В настоящий момент поддерживаются следующие аппендеры:
org.apache.log4j.FileAppender, org.apache.log4j.RollingFileAppender – запись в файл, задается формат вывода и т.д.
ru.diasoft.commons.logging.log4j.JDBCAppender – запись данных в SQL базу данных, параметры: url, user, password, jdbcDriver - параметры подключения к базе данных, bufferSize – количество строк журнала в буфере (размер буфера), maxBackupDayCount – количество дней хранения строки журнала в базе данных.
ru.diasoft.commons.logging.log4j.HBaseAppender – запись данных в NoSQL базу данных HBase.
Чтобы добавить свой аппендер(или несколько аппендеров), необходимо в файле log4j.xml(log4j.properties) настроить свой аппендер(ы) и просто добавить его к настройке журналирования с именем ru.diasoft.system.
2.2.1.Инициализация БД
Для хранения журналируемой информации используется таблица CORE_LOGS. Эта таблица создаётся в БД системной платформы при инициализации или обновлении БД системной платформы.
В случае, если необходимо вести запись журнала во внешнюю, по отношению к системной платформе, базу данных, необходимо создать таблицу CORE_LOGS в этой базе данных:
CREATE TABLE CORE_LOGS (
` DATED FLOAT NOT NULL, -- дата события, тип зависит от базы данных (FLOAT(53) для MSSQL, FLOAT(38) для остальных). Должна храниться дата до миллисекунды
LOGGER VARCHAR(255) NULL, -- имя настройки журналирования
LOGLEVEL VARCHAR(10) NOT NULL, -- уровень журналирования
USERNAME VARCHAR(255) NULL, -- логин пользователя
LOGUID VARCHAR(255) NULL, -- уникальный идентификатор запроса
MESSAGE VARCHAR(2000) NULL -- текст журналируемого сообщения, можно использовать clob
);
CREATE INDEX K01_CORE_LOGS ON CORE_LOGS (DATED ASC, USERNAME ASC);
CREATE INDEX K02_CORE_LOGS ON CORE_LOGS (DATED ASC, LOGUID ASC);
CREATE INDEX K03_CORE_LOGS ON CORE_LOGS (USERNAME ASC);
CREATE INDEX K04_CORE_LOGS ON CORE_LOGS (LOGUID ASC);
В случае промышленной эксплуатации, чтобы не загружать основную базу данных, sql- база для журналирования данных должна располагаться на отдельном сервере. В качестве базы данных можно использовать ”легкую” СУБД и выставить уровень изоляции в “Незавершенное (черновое) чтение” (read uncommitted).
2.3.Настройка log4j
Библиотека log4j может быть настроена либо через конфигурационный файл log4j.properties, либо через конфигурационный файл log4j.xml, при этом конфигурационный файл должен быть только один.
2.3.1.Настройка log4j через log4j.xml
Настройки для записи журнала в БД
Ниже приведён пример настройки аппендера для журналирования в базу данных через конфигурационный файл log4j.xml:
"DB" class="ru.diasoft.commons.logging.log4j.JDBCAppender">
"url" value="jdbc:oracle:thin:@soaora:1521:soaora11"/>
"driver" value="oracle.jdbc.driver.OracleDriver"/>
"user" value="user_id"/>
"password" value="password"/>
"org.apache.log4j.PatternLayout">
"ConversionPattern" value=" %m" />
Необязательные параметры -->
"bufferSize" value="5"/>
информации, значение по умолчанию -1 - хранить вечно -->
"maxBackupDayCount" value="15"/>
"maxActive" value="8" />
бездействовать, значение по умолчанию 8 -->
"maxIdle" value="8" />
бездействовать, значение по умолчанию 0 -->
"minIdle" value="0" />
прежде чем выбросить исключение, значение по умолчанию -1 ожидание на неопределенный
срок -->
"maxWait" value="-1" />
ru.diasoft.system -->
"ru.diasoft.system">
"DEBUG, DB" />
Настройки для записи журнала в файлы
Ниже приведен пример настройки аппендера для журналирования в файлы:
настройка аппендера -->
"SYSTEM" class="org.apache.log4j.RollingFileAppender">
"File" value="logs/system.log" />
"Append" value="false"/>
"MaxFileSize" value="1MB"/>
"MaxBackupIndex" value="2"/>
"Encoding" value="UTF-8"/>
"org.apache.log4j.PatternLayout">
"ConversionPattern" value="%d{dd-MM-yyyy HH:mm:ss.SSS} [%X{loginName}] [%p] [%c] - %m%n" />
добавление аппендера в логер ru.diasoft.system -->
"ru.diasoft.system">
"SYSTEM" />
2.3.2.Настройка log4j через log4j.properties
Настройки для записи журнала в БД
Ниже приведён пример настройки SQL-аппендера в log4j.properties (полный список параметров с комментариями приведен выше в примере настройки через log4j.xml):.
# Define the DB appender
log4j.appender.DB=ru.diasoft.commons.logging.log4j.JDBCAppender
log4j.appender.DB.url=jdbc:oracle:thin:@soaora:1521:soaora11
log4j.appender.DB.driver=oracle.jdbc.driver.OracleDriver
log4j.appender.DB.user=user_name
log4j.appender.DB.password=password
log4j.appender.DB.bufferSize=5
log4j.appender.DB.maxBackupDayCount=15
log4j.appender.DB.layout= org.apache.log4j.PatternLayout
log4j.appender.DB.layout.ConversionPattern=%m
# add DB appender
log4j.logger.ru.diasoft.system=DEBUG, DB
Настройки для записи журнала в файлы
Ниже приведён пример настройки файлового аппендера в log4j.properties (полный список параметров с комментариями приведен выше в примере настройки через log4j.xml):.
log4j.appender.logger=org.apache.log4j.RollingFileAppender
log4j.appender.logger.file=logs\logger.log
log4j.appender.logger.MaxFileSize=5MB
log4j.appender.logger.MaxBackupIndex=4
log4j.appender.logger.layout=org.apache.log4j.PatternLayout
log4j.appender.logger.layout.ConversionPattern=%d [%t] %-5p (%F:%L) - %m%n
# add appender
log4j.logger.org.apache.log4j.RollingFileAppender=DEBUG, logger
В ConversionPattern можно указать только само сообщение(ключ %m), уровень журналирования, название настройки журналирования можно не указывать. Данные значения автоматически пишутся в другие поля. Перенос строки (ключ %n) также не нужен.
3. Настройка журналирования через визуальный интерфейс
Доступ к журналированию по пользователю в администраторе платформы имеют пользователи с ролями:
dsa(Администратор системы)
dsso(Администратор безопасности)
Откройте форму «Настройки журналирования», кликнув на пункт меню «Администрирование -> Журналирование по пользователю -> Настройки журналирования»
Для добавления настройки журналирования нажмите кнопку «Добавить», отобразится форма добавления:
Поля формы:
Учётная запись пользователя(обязательное поле) – логин пользователя, по которому будет производиться журналирование, так же будет называться файл журнала, если журналирование выполняется на диск.
Настройки журналирования – стандартный список настроек, для задания своего выберите «Пользовательская» и введите название в появившееся поле «Пространство имён»
Заполните требуемые поля и нажмите кнопку «Выполнить».
Настройка журналирования добавится с уровнем журналирования «DEBUG».
Замечание! Журналирование по заданной настройке начнётся в зависимости от заданного времени задержки/обновления настроек журналирования (loggerUpdatePeriod и loggerInitialDelay).
4.Просмотр журналируемых данных
По умолчанию, журналируемая информация пишется в директорию %CONFIG_DIR%\logs в файлы вида %loginName%.log, где CONFIG_DIR директория, где лежат конфигурационные файлы (*-config.xml), loginName – логин пользователя.
Если журналы хранятся в базе данных, то просмотреть их можно через администратор платформы на форме «Просмотр журнала».
Форма «Просмотр журнала»:
Возможен поиск по всем хранимым параметрам
Можно выгрузить журнал в XLS-файл
Можно очистить журнал
При выделении строки в журнале полное сообщение события выводится в поле под таблицей
Доступ к журналированию по пользователю в администраторе платформы имеют пользователи с ролями:
dsa(Администратор системы)
dsso(Администратор безопасности)
Откройте форму «Просмотр журнала», кликнув на пункт меню «Администрирование -> Журналирование по пользователю -> Просмотр журнала»
Для отображения журнала заполните поле «Учётная запись» и нажмите «Найти».
Замечание! Просмотр журналов через модуль “администратор” платформы доступен, только если журналируемые данные хранятся в базе, используемой платформой (т.е. к которой подключены сервисы corews и adminws, и которая прописана в конфигурационных файлах этих сервисов, либо в конфигурационном файле common-config).
5.Подключение библиотеки журналирования к сервису
Для подключения библиотеки необходимо выполнить следующие простые шаги:
В pom.xml сервиса добавить зависимость(dependency)
ru.diasoft.commons.logging
logging
X.X.X.X
В качестве X.X.X.X указать последнюю стабильную версию библиотеки
В основном классе сервиса (помечен аннотацией @WebService, например ADMINWSIMPL)
а) Добавить переменную:
import ru.diasoft.commons.logging.ServiceLogManager;
….
private ServiceLogManager logManager;
б) В методе postInit (помечен аннотацией @PostConstruct) добавить:
logManager = new ServiceLogManager();
logManager.start();
в) В методе preDestroy(помечен аннотацией @PreDestroy) добавить:
logManager.stop();
г) В общей точке вызовов всех методов сервиса, обычно метод: dscall (в старой реализации сервисов), call(в новой реализации, получаемой при помощи платформенного генератора) добавить:
Добавить в импорт:
import ru.diasoft.commons.logging.LogContext;
import ru.diasoft.commons.logging.LogFactory;
Добавить в метод:
LogContext logContext = LogFactory.getLogContext();
logContext.put(LogContext.LOGIN_NAME, login); // логин пользователя
logContext.put(LogContext.UNIQUE_ID, UUID.randomUUID().toString()); // уникальный идентификатор, для всех логируемых данных вызываемого метода.
try {
…. Основной код метода
} finally {
logContext.remove(LogContext.LOGIN_NAME);
logContext.remove(LogContext.UNIQUE_ID);
}
В конфигурационный файл common-config.xml добавить логин и пароль (или хэш-код пароля) пользователя для доступа к методу получения текущих настроек журналирования из аdminws:
логин для доступа к adminws -->
dsa
хэш код пароля -->
7c222fb2927d828af22f592134e8932480637c0d
Для обратной совместимости, в случае отсутствия данных параметров, обновления уровней журналирования во время работы сервисов не происходит. Также можно задать два необязательных параметра:
1
1
-
По умолчанию, журналируемая информация пишется в директорию %CONFIG_DIR%\logs в файлы вида %loginName%.log, где CONFIG_DIR директория, где лежат конфигурационные файлы (*-config.xml), loginName – логин пользователя, если задан уровень журналирования без привязки к пользователю, данные пишутся в файл system.log
Вывод информации можно переопределить, настроив свой log4j аппендер (appender) или сразу несколько аппендеров. В настоящий момент поддерживаются следующие аппендеры:
org.apache.log4j.FileAppender, org.apache.log4j.RollingFileAppender – запись в файл, задается формат вывода и т.д.
ru.diasoft.commons.logging.log4j.JDBCAppender – запись данных в SQL базу данных, параметры: url, user, password, jdbcDriver - параметры подключения к базе данных, bufferSize – количество строк лога в буфере (размер буфера), maxBackupDayCount – количество дней хранения строки лога в базе данных.
ru.diasoft.commons.logging.log4j.HBaseAppender – запиcь данных в NoSQL базу данных HBase.
Настройка собственного аппендера описана в разделе 2.3.
|
