{"id":15288826,"url":"https://github.com/funbox/loggun","last_synced_at":"2025-04-13T08:11:26.721Z","repository":{"id":56881907,"uuid":"237419323","full_name":"funbox/loggun","owner":"funbox","description":"Приводит логи приложения к единому формату","archived":false,"fork":false,"pushed_at":"2023-10-11T06:08:32.000Z","size":105,"stargazers_count":6,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-27T00:05:12.472Z","etag":null,"topics":["logger","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-31T11:46:57.000Z","updated_at":"2023-10-11T06:08:38.000Z","dependencies_parsed_at":"2024-10-22T10:19:32.216Z","dependency_job_id":null,"html_url":"https://github.com/funbox/loggun","commit_stats":{"total_commits":65,"total_committers":5,"mean_commits":13.0,"dds":0.5692307692307692,"last_synced_commit":"68a9efb5be07bafce6e839ab28a050338b073a1f"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Floggun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Floggun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Floggun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Floggun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/loggun/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248182079,"owners_count":21060893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logger","ruby","ruby-on-rails"],"created_at":"2024-09-30T15:53:19.578Z","updated_at":"2025-04-13T08:11:26.693Z","avatar_url":"https://github.com/funbox.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Loggun\n\n[![Gem Version](https://badge.fury.io/rb/loggun.svg)](https://badge.fury.io/rb/loggun)\n[![Build Status](https://travis-ci.org/funbox/loggun.svg?branch=master)](https://travis-ci.org/funbox/loggun)\n\nПриводит логи приложения к единому формату.\n\n## Содержание\n\n- [Установка](#установка)\n- [Использование](#использование)\n- [Конфигурация](#конфигурация)\n  - [Настройки](#настройки)\n  - [Модификаторы](#модификаторы)\n    - [Rails модификатор](#rails-модификатор)\n    - [Active Record модификатор](#active-record-модификатор)\n    - [Sidekiq модификатор](#sidekiq-модификатор)\n    - [Clockwork модификатор](#clockwork-модификатор)\n    - [Модификатор исходящих HTTP-запросов](#модификатор-исходящих-http-запросов)\n    - [Модификатор входящих запросов в Rails](#модификатор-входящих-запросов-в-rails)\n    - [Пользовательские модификаторы](#пользовательские-модификаторы)\n  - [Хелперы](#хелперы)\n\n## Установка\n\nЧтобы установить гем, добавьте его в Gemfile:\n\n```ruby\ngem 'loggun'\n```\n\nИ выполните команду:\n\n```bash\n$ bundle\n```\n\n## Использование\n\nLoggun можно использовать как обертку для вашего `logger`. Для этого необходимо передать\nему инстанс логгера и настроить его `formatter`:\n\n```ruby\nLoggun.logger = Rails.logger\nLoggun.logger.formatter = Loggun::Formatter.new\n```\n\nТеперь можно использовать Loggun для логирования в стандартизированном формате:\n\n```ruby\nLoggun.info('http_request.api.request', user_id: current_user.id)\n#=\u003e 2020-04-11T22:35:04.225+03:00 - 170715 INFO http_request.api.request - {\"user_id\": 5465}\n...\nLoggun.info('http_request.api.response', user_id: current_user.id, success: true)\n#=\u003e 2020-04-11T22:35:04.225+03:00 - 170715 INFO http_request.api.response - {\"user_id\": 5465, \"success\": true} \n``` \n\n## Конфигурация\n\nКонфигурацию гема необходимо производить при инициализации приложения. Например, так:\n\n```ruby\nLoggun::Config.configure do |config|\n  config.precision = :milliseconds\n  config.pattern = '%{time} - %{pid} %{severity} %{type} %{tags_text} %{message}'\n  config.parent_transaction_to_message = false\n  config.message_format = :json\n\n  config.modifiers.rails = true\n  config.modifiers.sidekiq = false\n  config.modifiers.clockwork = false\n  config.modifiers.incoming_http = false\n  config.modifiers.outgoing_http = false\nend\n```\n\n### Настройки\n\nВсе настройки опциональны.\n\n- `precision` — точность отметок времени.\n\n  Может принимать одно из следующих значений:\n  `sec`, `seconds`, `ms`, `millis`, `milliseconds`, `us`, `micros`, `microseconds`, `ns`, `nanos`, `nanoseconds`.\n  \n  По умолчанию `milliseconds`.\n\n- `pattern` — текстовый шаблон для формата вывода данных в лог.   \n\n  Доступные ключи внутри шаблона: `time`, `pid`, `severity`, `type`, `tags_text`, `message`, `parent_transaction`.\n\n- `parent_transaction_to_message` — если `true`, то значение `parent_transaction` будет добавлено в тело логируемого сообщения.\n \n  Ключ `parent_transaction` в шаблоне `pattern` можно использовать вне зависимости от значения этой настройки. \n  \n- `force_utc` — если `true`, то значение `time` будет переведено в UTC.\n  \n  По умолчанию `false`.\n\n- `message_format` — формат переменной `message` в шаблоне `pattern`. \n\n  Доступные значения:\n   \n  - `:json` — `message` логируется как JSON-строка;\n  - `:key_value` — `message` логируется в формате `key1=value1 key2=value2`.\n\n- `log_format` — формат лога. \n\n  Доступные значения:\n   \n  - `:json` — лог формируется как JSON-строка игнорируя шаблон `pattern` и настройку `message_format`;\n  - `:plain` — лог формируется по шаблону `pattern`.\n  \n  По умолчанию `:plain`.\n  \n  При `log_format == :json` в `message` будет попадать только сообщение, которое было передано строкой. Сообщение, \n  переданное хешем попадет в поле `metadata`. Пример:\n  ```ruby\n    Loggun.info(\"my.best.action\", \"message string\", test: true)\n    # {\n    #    \"metadata\":{\"test\":true},\n    #    \"message\":\"message string\",\n    #    \"type\":\"my.best.action\",\n    #    \"timestamp\":\"2020-09-22T14:57:22.233+03:00\",\n    #    \"severity\":\"INFO\",\n    #    ...\n    #    }\n  ```\n      \n- `exclude_keys` — список ключей, которые будут исключены из лога.\n\n   Используется, если `log_format` имеет значение `:json` и список `only_keys` пуст.\n\n- `only_keys` — список ключей, которые будут включены в JSON-строку.\n   \n   Используется, если `log_format` имеет значение `:json`.\n \n- `modifiers` — модификаторы для переопределения формата логирования указанного компонента. См. «[Модификаторы](#модификаторы)».\n\n### Модификаторы\n\nКаждый модифкатор может быть активирован двумя равнозначными способами:\n\n```ruby\nconfig.modifiers.rails = true\n```\n\nили\n\n```ruby\nconfig.modifiers.rails.enable = true\n```\n\n(В качестве примера активируется Rails модификатор, но может быть любой другой.)\n\n#### Rails модификатор \n\n`config.modifier.rails`\n\nМодифицирует форматирование логгера Rails.\n\n#### Active Record модификатор\n\n`config.modifier.active_record`\n\nДобавляет (именно добавляет, а не модифицирует) нового подписчика на SQL-события.\n\nSQL начинает дополнительно логироваться в Loggun формате, `severity` — `info`. Например:\n\n```text\n2020-04-12T20:08:52.913+03:00 - 487257 INFO storage.sql.query - {\"sql\":\"SELECT 1\",\"name\":null,\"duration\":0.837}\n```\n\nДополнительные настройки:\n\n- `log_subscriber_class_name` — имя класса, реализующего логирование SQL-события.\n\n  Необходим метод `#sql`. По умолчанию: `::Loggun::Modifiers::ActiveRecord::LoggunLogSubscriber`.\n\n- `payload_keys` — необходимые ключи в полезной нарзуке. Используется в классе по умолчанию. \n   \n  Доступные ключи: `%i[sql name duration source]`.\n\nПример:\n\n```ruby\nLoggun::Config.configure do |config|\n  #...\n  config.modifiers.active_record.enable = true\n  config.modifiers.active_record.log_subscriber_class_name = 'MyApp::MyLogSubscriber'\n  config.modifiers.active_record.payload_keys = %i[sql duration]\n  #...\nend\n```\n\n#### Sidekiq модификатор \n\n`config.modifiers.sidekiq`\n\nМодифицирует форматирование логгера Sidekiq.\n\n#### Clockwork модификатор\n\n`config.modifiers.clockwork`\n \nМодифицирует форматирование логгера Clockwork.\n\n#### Модификатор исходящих HTTP-запросов\n\n`config.modifiers.outgoing_http`\n\nДобавляет логирование исходящих HTTP-запросов. \nНа данный момент поддерживаются только запросы, выполненные с помощью гема `HTTP`.\n\n#### Модификатор входящих запросов в Rails\n\n `config.modifiers.incoming_http`\n \nДобавляет логирование входящих HTTP-запросов для контроллеров Rails.\n\nМожет иметь дополнительные настройки:\n\n- `controllers` — массив имён базовых контроллеров, для которых необходимо добавить указанное логирование.\n\n- `success_condition` — лямбда, определяющая, содержит ли успех ответ экшена.\n\n  Например: `-\u003e { JSON.parse(response.body)['result'] == 'ok' }`\n\n- `error_info` — лямбда, позволяющая добавить в лог информацию об ошибке, содержащейся в неуспешном ответе экшена. \n\n  Например: `-\u003e { JSON.parse(response.body)['error_code'] }`\n\n\nПример (приведены значения по умолчанию):\n\n```ruby\nLoggun::Config.configure do |config|\n  #...\n  config.modifiers.incoming_http.enable = true\n  config.modifiers.incoming_http.controllers = ['ApplicationController']\n  config.modifiers.incoming_http.success_condition = -\u003e { response.code == '200' }\n  config.modifiers.incoming_http.error_info = -\u003e { nil }\n  #...\nend\n```\n\n**Для Rails 6 и выше данный модификатор может работать некорректно.** \n\nВ этом случае можно добавить в требуемый базовый контроллер строку:\n\n```ruby\ninclude Loggun::HttpHelpers\n```\n\nЭто делает настройки `enable` и `controllers` модификатора безсполезными, \nоднако позволяет гарантированно логировать входящие HTTP-запросы.\n\nНастройки `success_condition` и `error_info` продолжают использоваться и могут быть установлены требуемым образом.\n\n#### Пользовательские модификаторы\n\nПомимо указанных модификаторов существует возможность добавить собственный. \nНеобходимо уснаследовать его от `Loggun::Modifiers::Base` и указать в методе `apply` все необходимые действия:\n\n```ruby\nrequire 'sinatra/custom_logger'\n\nclass NewModifier \u003c Loggun::Modifiers::Base\n  def apply\n    Loggun::Config.setup_formatter(Sinatra::CustomLogger)\n  end\nend\n```\n\nЗатем необходимо добавить его при конфигурации гема:\n\n\n```ruby\nLoggun::Config.configure do |config|\n  #...\n  config.add_mofifier NewModifier\n  #...\nend\n```\n\n### Хелперы\n\nПодключение хэлперов в класс позволяет использовать методы логирования `log_info` и `log_error`, \nа также генерировать идентификатор транзации для каждого метода класса.\n\nНапример:\n\n```ruby\nclass SomeClass\n  include Loggun::Helpers\n\n  log_options entity_action: :method_name, as_transaction: true, only: %i[download_data]\n\n  def download_data\n    log_info 'http_request', 'Information'\n    # ... make http request here\n    log_info 'http_response', success: true\n  end\nend\n```\n\nПри вызове `#download_data` будет следующий вывод в лог:\n\n```\n2020-03-04T16:58:38.207+05:00 - 28476 INFO http_request.some_class.download_data#ffg5431_1583323118203 - {\"message\":[\"Information\"]}\n2020-03-04T16:58:38.208+05:00 - 28476 INFO http_response.some_class.download_data#ffg5431_1583323118203 - {\"success\": true}\n```\n\n**Важно**, что с хэлпером `log_options` необходимо использовать только методы вида `log_\u003cseverity\u003e`. \nМетоды модуля `Loggun` не будут работать.\n\nСписок всех опций хэлпера `log_options`:\n\n- `entity_name` — имя сущности метода, `string`;\n- `entity_action` — действие сущности метода, `string`;\n- `as_transaction` — добавлять ли уникальный ID транзакции для метода, `boolean`;\n- `transaction_generator` — собственный генератор ID транзакции, `lambda`;\n- `log_all_methods` — применять ли хэлпер ко всем методам, `boolean`;\n- `only` — список методов, для которых необходимо применить хэлпер (работает только когда `log_all_methods = false`), `Array{Symbol}`;\n- `except` — список методов, которые надо исключить для хэлпера, `Array{Symbol}`;\n- `log_transaction_except` — список методов, логирование которых не нужно обогащать ID транзакции, `Array{Symbol}`.\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Floggun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Floggun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Floggun/lists"}