Skip to content

Chronica

Jump to bottom Edit New page
Nikita Roshupkin edited this page Oct 15, 2015 · 1 revision

##Общее представление Chronica это специальный фреймворк используемый для логирования сообщений в Erlang. Он осуществляет более простой способ введения журналов в Erlang-приложениях.

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

  • Быстрее, легче, гибче!
  • Возможность создавать множество потоков записей, правил вывода и форматов вывода
  • Возможность задавать формат для каждого backend'а индивидуально
  • Поддержка удаленного “отщепления” потока логов с фильтрацией
  • Различные режимы фильтрации логов
  • Легкая миграция проектов, ранее использующих lager
  • Малая нагрузка на систему при отключенном логировании
  • Гибкий конфигурационный файл
  • Запись бинарных логов
  • Возможность реализации и добавления внешних backend'ов
  • Поддержка unicode
  • Ротация логов
  • Поддержка цветного терминального вывода
  • Возможность изменения фильтрации логов на лету
  • Тегирование log-сообщений
  • Быстрый старт приложения при повторном запуске на узле

Использование Логер оформлен в виде erlang application — chronica. Для того, чтобы начать работать с chronica, достаточно её указать в app проекта.
Также для работы Chronica требуется добавить опцию в rebar:

{parse_transform, pt_chronica}

Альтернативой является, добавление в файлах, в которых используется логирование, строки:

-include_lib("chronica/include/chronica.hrl").

Также для проекта требуется конфигурационный файл. В него нужно добавить секцию {chronica, [] }, в которой прописываются конфигурационные данные. При его отсутствии, используются настройки по умолчанию.

Фреймворк chronica поддерживает следующие уровни логирования:

(MAX) debug -> trace -> info -> warning -> (MIN) error

При этом ранее стоящий уровень логов включается все последующие за ним уровни. Чтобы была возможность логировать только один уровень, даже если он включает в себя несколько, и выделить специфичные логи, используется тегирование. Tag := atom, он подставляется перед "Format" и [Args], и должен быть вычислен на момент компиляции. Т.е. лучше не писать log:error(MyTag, Str, Args), т.к. значение MyTag будет известно только при выполнении.

После же подключения хроники к проекту, можно писать логи, используя модуль log, содержащий функции error, warning, info, trace и debug соответствующие уровням логирования.

log:Level("String"),
log:Level("Format", [Args]),
log:Level(Tag, "Format", [Args]),
log:Level([Tags], "Format", [Args]),
Tag := atom

где Level один из перечисленных функций логирования.

Основные макросы для вывода сообщений в лог: DBG, TRACE, INFO, WARN, ERR. Они могут быть вызваны двумя способами

LEVEL(Format)
LEVEL(Format, Args)

В случае использования макросов, также добавить

-include_lib("chronica/include/chronica_macro.hrl").

##Конфигурационный файл Для ознакомления со всеми возможностями настройки sys_doc.config

##%stack Из-за того, что в Chronica вычисление аргументов при вызове log:Level(), где Level это (error, warning, info, trace, debug) может происходить не в контексте вызвавшего процесса, был добавлен специальный флаг %stack, который работает данным образом:

log:Level("%stack") преобразуется в 
begin 
    Chronica_stacktrace = erlang:get_stacktrace(), 
    log:Level("~p", [Chronica_stacktrace]).
end

##Тегирование Тегирование в Chronica позволяет создать группы уникальных логов, которые будут писаться в определенный backend. Для того чтобы была возможность быстро найти нужное(ые) лог сообщение. Были введены пользовательские и служебные теги.

  • Под пользовательскими тегами подразумевается Tags, которые будут указаны перед форматом данных и аргументами. Пример:
log:error([my_teg], “test”).
  • Под служебными тегами подразумевается Tags, которые были добавлены во время compile-time. Такими тегами являются
    • Тег имени модуля
    • Тег имени модуля с указанием строки расположения данного log сообщения Пример:
1    -module(testing).
2    -export([test/0]).
3    -include_lib("chronica/include/chronica.hrl").
4    test() ->
5        log:error(“test”).

После Compile-time у log:error появится теги данного вида [testing, testing_5]

##log:todo Применяется для того чтобы отследить участок кода, который считается незавершённым. Работает только с константными данными, и выводит расположение вызываемого log:todo() во время компиляция.

Пример:

1    -module(testing).
2    -export([test/0]).
3    -include_lib("chronica/include/chronica.hrl").
4    test() ->
5        log:todo(“test”).

Out:
    (полный путь)/chronica_testing.erl:214: TODO: test

##Rules Rules - это правила выборки лог сообщений для указанных Flows. Данное поле, просматривая уровень логирования, служебные и пользовательские теги установленные у лог сообщения, решает, будет ли оно передано в Flows или будет проигнорировано.
Все или часть заголовков могут быть выключены в поле Rules. Если заголовок выключен, тогда он будет проигнорирован.

Пример:

{warning_file_example1,      “*”,    warning,    [warning_file], off}, 
данное правило будет проигнорировано

{warning_file_example2,      “*”,    warning,    [warning_file], on},
данное правило выполнит все логи уровня warning или ниже

{warning_file_example2,      “my_tag”,    warning,    [warning_file], on},
данное правило выполнит все логи уровня warning или ниже, если у них присутствует тег “my_tag”

##Flows Flows - это именованные потоки, которые пишут в файл, выводят на экран и передаются по udp. Здесь также решается какой будет формат вывода и вид представления в binary или в текстовом.

Пример:

{warning_file, [{file, "debug.bin", binary}]},
Поток будет писать в debug.bin, дефолтным форматом, в бинарном виде

{warning_file, [{file, "warning.txt"}]},
Поток будет писать в warning.txt, дефолтным форматом, в текстовом виде

{warning_file, [{tty, short}]},
Поток будет писать на консоль, short форматом, в текстовом виде

##Formats В sys.config присутствует поле Formats, оно отвечает за вид вывода лог сообщений на терминал или в файл.

Если вы хотите переопределить стандартный способ вывода, используйте заголовок default:

{formats,{ [ {default, “строка вывода”} ] }

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

default по умолчанию
{flows, [{screen, [{tty, default}]}] }
Out:
    2015-09-27 14:59:32.012401 WARN  <0.130.0> [testing_chronica_logs:testing_short_warning_file/1:57]: test chronica

переопределенный default
{flows, [ {screen, [ {tty, default} ] } ] },
{formats,[{default, "%H:%Mi:%S.%Ms [%Priority] %Message\n"}]},
Out:
    15:03:15.702088 [warning] test chronica

Если вы хотите задать уникальный способ вывода, то задайте уникальный заголовок и укажите его в поле flows одного из заголовков:

{flows, [ {file, "warning_log", my_default} ] },
{formats, [ {my_default, “строка вывода”} ] }

##Настройка на лету Применяются для модифицирования конфигурационного файла

  • chronica_manager:update_rule_inwork(name_rule, false | true)
    Данная функция отвечает за включение и отключение заголовков в поле rules

  • chronica_manager:active(false | true)
    Данная функция отвечает за активацию или дезактивацию работы логера в Chronica

Применяются для расширения функционала

  • chronica_manager:add_application(App)
    Данная функция позволяет зарегистрировать application во время работы Chronica

##App Chronica Важно отметить, что пользовательские модули которые используют сервис chronica посредством вызова log:Level должны быть организованы согласно OTP Design Principles. Application же, должен быть зависим от приложения chronica (т.е. в ресурсном файле .app, должен быть прописан в свойстве applications, на ряду с kernel и stdlib).

Это связанно с тем, что модуль приложения при инициализации, может содержать вызовы chronica. Отсюда следует, что если к примеру мы попытаемся использовать вызов вида log:Level в модуле, который запущен до Chronica, то такой вызов не приведет к ожидаемому результату.

##Планы Теги константные
Регистрация модулей

Add a custom footer
Add a custom sidebar
Clone this wiki locally