README.md

Loggun

Приводит логи приложения к единому формату.

Содержание

• Установка
• Использование
• Конфигурация
  • Настройки
  • Модификаторы
    • Rails модификатор
    • Active Record модификатор
    • Sidekiq модификатор
    • Clockwork модификатор
    • Модификатор исходящих HTTP-запросов
    • Модификатор входящих запросов в Rails
    • Пользовательские модификаторы
  • Хелперы

Установка

Чтобы установить гем, добавьте его в Gemfile:

gem 'loggun'

И выполните команду:

$ bundle

Использование

Loggun можно использовать как обертку для вашего logger. Для этого необходимо передать ему инстанс логгера и настроить его formatter:

Loggun.logger = Rails.logger
Loggun.logger.formatter = Loggun::Formatter.new

Теперь можно использовать Loggun для логирования в стандартизированном формате:

Loggun.info('http_request.api.request', user_id: current_user.id)
#=> 2020-04-11T22:35:04.225+03:00 - 170715 INFO http_request.api.request - {"user_id": 5465}
...
Loggun.info('http_request.api.response', user_id: current_user.id, success: true)
#=> 2020-04-11T22:35:04.225+03:00 - 170715 INFO http_request.api.response - {"user_id": 5465, "success": true} 

Конфигурация

Конфигурацию гема необходимо производить при инициализации приложения. Например, так:

Loggun::Config.configure do |config|
  config.precision = :milliseconds
  config.pattern = '%{time} - %{pid} %{severity} %{type} %{tags_text} %{message}'
  config.parent_transaction_to_message = false
  config.message_format = :json

  config.modifiers.rails = true
  config.modifiers.sidekiq = false
  config.modifiers.clockwork = false
  config.modifiers.incoming_http = false
  config.modifiers.outgoing_http = false
end

Настройки

Все настройки опциональны.

• precision — точность отметок времени.

  Может принимать одно из следующих значений: sec, seconds, ms, millis, milliseconds, us, micros, microseconds, ns, nanos, nanoseconds.

  По умолчанию milliseconds.

• pattern — текстовый шаблон для формата вывода данных в лог.

  Доступные ключи внутри шаблона: time, pid, severity, type, tags_text, message, parent_transaction.

• parent_transaction_to_message — если true, то значение parent_transaction будет добавлено в тело логируемого сообщения.

  Ключ parent_transaction в шаблоне pattern можно использовать вне зависимости от значения этой настройки.

• force_utc — если true, то значение time будет переведено в UTC.

  По умолчанию false.

• message_format — формат переменной message в шаблоне pattern.

  Доступные значения:

  • :json — message логируется как JSON-строка;
  • :key_value — message логируется в формате key1=value1 key2=value2.

• log_format — формат лога.

  Доступные значения:

  • :json — лог формируется как JSON-строка игнорируя шаблон pattern и настройку message_format;
  • :plain — лог формируется по шаблону pattern.

  По умолчанию :plain.

  При log_format == :json в message будет попадать только сообщение, которое было передано строкой. Сообщение, переданное хешем попадет в поле metadata. Пример:

    Loggun.info("my.best.action", "message string", test: true)
    # {
    #    "metadata":{"test":true},
    #    "message":"message string",
    #    "type":"my.best.action",
    #    "timestamp":"2020-09-22T14:57:22.233+03:00",
    #    "severity":"INFO",
    #    ...
    #    }

• exclude_keys — список ключей, которые будут исключены из лога.

  Используется, если log_format имеет значение :json и список only_keys пуст.

• only_keys — список ключей, которые будут включены в JSON-строку.

  Используется, если log_format имеет значение :json.

• modifiers — модификаторы для переопределения формата логирования указанного компонента. См. «Модификаторы».

Модификаторы

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

config.modifiers.rails = true

или

config.modifiers.rails.enable = true

(В качестве примера активируется Rails модификатор, но может быть любой другой.)

Rails модификатор

config.modifier.rails

Модифицирует форматирование логгера Rails.

Active Record модификатор

config.modifier.active_record

Добавляет (именно добавляет, а не модифицирует) нового подписчика на SQL-события.

SQL начинает дополнительно логироваться в Loggun формате, severity — info. Например:

2020-04-12T20:08:52.913+03:00 - 487257 INFO storage.sql.query - {"sql":"SELECT 1","name":null,"duration":0.837}

Дополнительные настройки:

• log_subscriber_class_name — имя класса, реализующего логирование SQL-события.

  Необходим метод #sql. По умолчанию: ::Loggun::Modifiers::ActiveRecord::LoggunLogSubscriber.

• payload_keys — необходимые ключи в полезной нарзуке. Используется в классе по умолчанию.

  Доступные ключи: %i[sql name duration source].

Пример:

Loggun::Config.configure do |config|
  #...
  config.modifiers.active_record.enable = true
  config.modifiers.active_record.log_subscriber_class_name = 'MyApp::MyLogSubscriber'
  config.modifiers.active_record.payload_keys = %i[sql duration]
  #...
end

Sidekiq модификатор

config.modifiers.sidekiq

Модифицирует форматирование логгера Sidekiq.

Clockwork модификатор

config.modifiers.clockwork

Модифицирует форматирование логгера Clockwork.

Модификатор исходящих HTTP-запросов

config.modifiers.outgoing_http

Добавляет логирование исходящих HTTP-запросов. На данный момент поддерживаются только запросы, выполненные с помощью гема HTTP.

Модификатор входящих запросов в Rails

config.modifiers.incoming_http

Добавляет логирование входящих HTTP-запросов для контроллеров Rails.

Может иметь дополнительные настройки:

• controllers — массив имён базовых контроллеров, для которых необходимо добавить указанное логирование.

• success_condition — лямбда, определяющая, содержит ли успех ответ экшена.

  Например: -> { JSON.parse(response.body)['result'] == 'ok' }

• error_info — лямбда, позволяющая добавить в лог информацию об ошибке, содержащейся в неуспешном ответе экшена.

  Например: -> { JSON.parse(response.body)['error_code'] }

Пример (приведены значения по умолчанию):

Loggun::Config.configure do |config|
  #...
  config.modifiers.incoming_http.enable = true
  config.modifiers.incoming_http.controllers = ['ApplicationController']
  config.modifiers.incoming_http.success_condition = -> { response.code == '200' }
  config.modifiers.incoming_http.error_info = -> { nil }
  #...
end

Для Rails 6 и выше данный модификатор может работать некорректно.

В этом случае можно добавить в требуемый базовый контроллер строку:

include Loggun::HttpHelpers

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

Настройки success_condition и error_info продолжают использоваться и могут быть установлены требуемым образом.

Пользовательские модификаторы

Помимо указанных модификаторов существует возможность добавить собственный. Необходимо уснаследовать его от Loggun::Modifiers::Base и указать в методе apply все необходимые действия:

require 'sinatra/custom_logger'

class NewModifier < Loggun::Modifiers::Base
  def apply
    Loggun::Config.setup_formatter(Sinatra::CustomLogger)
  end
end

Затем необходимо добавить его при конфигурации гема:

Loggun::Config.configure do |config|
  #...
  config.add_mofifier NewModifier
  #...
end

Хелперы

Подключение хэлперов в класс позволяет использовать методы логирования log_info и log_error, а также генерировать идентификатор транзации для каждого метода класса.

Например:

class SomeClass
  include Loggun::Helpers

  log_options entity_action: :method_name, as_transaction: true, only: %i[download_data]

  def download_data
    log_info 'http_request', 'Information'
    # ... make http request here
    log_info 'http_response', success: true
  end
end

При вызове #download_data будет следующий вывод в лог:

2020-03-04T16:58:38.207+05:00 - 28476 INFO http_request.some_class.download_data#ffg5431_1583323118203 - {"message":["Information"]}
2020-03-04T16:58:38.208+05:00 - 28476 INFO http_response.some_class.download_data#ffg5431_1583323118203 - {"success": true}

Важно, что с хэлпером log_options необходимо использовать только методы вида log_<severity>. Методы модуля Loggun не будут работать.

Список всех опций хэлпера log_options:

• entity_name — имя сущности метода, string;
• entity_action — действие сущности метода, string;
• as_transaction — добавлять ли уникальный ID транзакции для метода, boolean;
• transaction_generator — собственный генератор ID транзакции, lambda;
• log_all_methods — применять ли хэлпер ко всем методам, boolean;
• only — список методов, для которых необходимо применить хэлпер (работает только когда log_all_methods = false), Array{Symbol};
• except — список методов, которые надо исключить для хэлпера, Array{Symbol};
• log_transaction_except — список методов, логирование которых не нужно обогащать ID транзакции, Array{Symbol}.