{"id":24370151,"url":"https://github.com/oscript-library/logos","last_synced_at":"2026-03-14T09:01:32.909Z","repository":{"id":10908768,"uuid":"67449851","full_name":"oscript-library/logos","owner":"oscript-library","description":"Библиотека логирования в стиле log4j","archived":false,"fork":false,"pushed_at":"2025-02-02T08:53:08.000Z","size":1506,"stargazers_count":32,"open_issues_count":6,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-02-02T09:27:10.151Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"1C Enterprise","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oscript-library.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-09-05T20:44:30.000Z","updated_at":"2025-02-02T08:52:07.000Z","dependencies_parsed_at":"2025-02-02T09:24:06.268Z","dependency_job_id":"4d28af1e-24d2-4ac6-afea-f91c441e1fa3","html_url":"https://github.com/oscript-library/logos","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscript-library%2Flogos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscript-library%2Flogos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscript-library%2Flogos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscript-library%2Flogos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oscript-library","download_url":"https://codeload.github.com/oscript-library/logos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243203891,"owners_count":20253367,"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":[],"created_at":"2025-01-19T04:12:47.541Z","updated_at":"2025-12-24T09:50:53.932Z","avatar_url":"https://github.com/oscript-library.png","language":"1C Enterprise","readme":"# Логирование в стиле log4j\n\nБиблиотека предназначена для удобного вывода сообщений в привязке к их \"уровням важности\"\n \nФункционал logos не повторяет полностью log4j, а, скорее, берет из него какие-то аспекты поведения.\n \n# Использование\n\n## Именованные журналы сообщений (Логи)\n\nКаждый лог имеет собственное имя, по которому он может быть идентифицирован. Имена логов глобально видимы и любой из них может быть получен по имени лога.\n\nДля того, чтобы начать логирование, требуется вызвать метод `ПолучитьЛог` модуля `Логирование`\n\n    Лог = Логирование.ПолучитьЛог(\"oscript.app.messages\");\n    \n### Соглашение об именовании\n\nПринята следующая схема именования логов:\n\n    область.класс_приложения.имя_лога\n    \n* Область - это произвольное имя, определяющее некую совокупность возможных логов. Часто, в качестве области используется имя поставщика приложения, либо имя набора библиотек. Для всех пакетов, входящих в oscript-library используется имя области \"oscript\". Приложения, создаваемые, например, в рамках гипотетического проекта \"Аврора\" могут использовать область \"aurora\".\n* Класс_приложения - это разделитель на тип модуля - библиотека, или приложение. Например, библиотечный пакет \"cmdline\" использует класс `lib`, а консольное приложение \"gitsync\" - класс 'app'\n* Имя_лога - это, собственно, идентификатор журнала.\n\n### Примечание\n\nВ отличие от log4j логи в logos не являются иерархическими, но в перспективе могут стать таковыми.\n\n## Уровни логирования\n\nСуществует 5 уровней важности сообщений:\n\n* Отладка\n* Информация\n* Предупреждение\n* Ошибка\n* Критичная ошибка\n\nДля каждого из уровней logos предоставляет отдельный метод, который выводит сообщение с данным уровнем важности. В процессе эксплуатации приложения для каждого из логов можно устанавливать уровень выводимых сообщений. Например, если установлен уровень \"Предупреждение\", то выводиться будут только предупреждения или более важные сообщения (Ошибка, КритичнаяОшибка)\n\n    Лог.УстановитьУровень(УровниЛога.Отладка) // выводить все, в т.ч. отладочные сообщения\n    \nПо умолчанию установлен уровень \"Информация\".\n\n### Пример использования\n\n    Лог = Логирование.ПолучитьЛог(\"oscript.test.levels\");\n    Лог.УстановитьУровень(УровниЛога.Ошибка);\n    \n    Лог.Отладка(\"Переменная А = 7\");\n    Лог.Информация(\"Переменная А = 7\");    \n    Лог.Ошибка(\"Неверно указан путь к файлу!\");\n    \n    ПеремА = \"А\";\n    Лог.Отладка(\"Переменная %1 = %2\", ПеремА, 7);\n    Лог.Информация(\"Переменная %1 = %2\", ПеремА, 7);\n    Лог.Ошибка(\"Неверно указан путь к файлу %1!\", ПеремА);\n    \n## Способы вывода (appenders)\n\nПриложение выводит сообщения в лог, а сам лог может выводиться в произвольное место. За конкретную реализацию вывода отвечает *Способ вывода*. В Log4j это называется appender.\n\nВ составе logos поставляется 2 способа вывода - в консоль и в файл.\nПричем, способы вывода - это список, т.е. лог может писаться в несколько мест одновременно.\n\n    ФайлЖурнала = Новый ВыводЛогаВФайл\n    ФайлЖурнала.ОткрытьФайл(\"/var/log/oscript.test.log\");\n    Лог.ДобавитьСпособВывода(ФайлЖурнала);\n    Лог.Информация(\"Это строка лога\");\n    Лог.Закрыть(); // при включении логирования в файл рекомендуется закрывать лог.\n\n### Особенности добавления Способов вывода\n\nПри создании лога в него автоматически будет добавлен способ вывода *ВыводЛогаВКонсоль*. Однако, если вручную в лог будет добавлен другой способ вывода, то \"автоспособ\" будет удален. Иными словами, пример кода выше будет писать только в файл, т.к. консольный вывод при ручном добавлении способа вывода будет отключен.\n\n### Особенности формирования логов с дополнительными полями\n\nВ связи с вводом `API v2` для форматирования сообщений, появилась возможность передавать в объект форматирования дополнительные поля.\n\nДля создания лога с дополнительными полями необходимо использовать следующие функции:\n\n* `Поля` - принимает на вход поля и значения, где первый параметр имя поля, а второй значение поля и так до 4 полей\n\n* `ПоляИз` - принимает на соответствие или структуру полей для лога\n\n\u003e Важно! Надо помнить, что при вызове этих функций создается объект класса `Лог`, вне модуля `Логирование`. И он не меняет `Лог` с таким же именем и живет только внутри вызванных методов\n\nПример использования:\n\n```bsl\n    ЛогБиблиотеки = Логирование.ПолучитьЛог(\"oscript.lib.test\");\n  \n    ПоляЛога = Новый Структура(\"ДопПоле, ДопПоле2\", \"ДопПоле\", \"ДопПоле2\");\n\n    Лог = ЛогБиблиотеки.ПоляИз(ПоляЛога);\n\n    Лог.Отладка(\"Это отладка\");\n\n    // ИЛИ \n\n\tЛогБиблиотеки.Поля(\"ДатаВремя\", ТекущаяДата(), \"ПростоПоле\", \"ПростоПоле\").Информация(\"Привет\");\n\n```\n\n\n## Форматирование сообщений\n\nЗа форматирование выводимых сообщений отвечает *Раскладка*. Раскладка по умолчанию форматирует сообщения следующим образом:\n\n    УРОВЕНЬСООБЩЕНИЯ - ТекстСообщения\n    \nРаскладка - это класс, реализующий метод *Форматировать(Знач Уровень, Знач Сообщение)*. Установить собственную раскладку можно методом \"УстановитьРаскладку\".\n\n* API v1\n    ```bsl\n    Функция Форматировать(Знач Уровень, Знач Сообщение) Экспорт\n\n        Возврат СтрШаблон(\"%1: %2 - %3\", ТекущаяДата(), УровниЛога.НаименованиеУровня(Уровень), Сообщение);\n    \n    КонецФункции\n    ``` \n* API v2\n     ```bsl\n    Функция ПолучитьФорматированноеСообщение(Знач СобытиеЛога) Экспорт\n        \n        // СобытиеЛога - Объект с методами\n        //   * ПолучитьУровень() - Число - уровень лога\n        //   * ПолучитьСообщение() - Строка - текст сообщения\n        //   * ПолучитьИмяЛога() - Строка - имя лога\n        //   * ПолучитьВремяСобытия() - Число - Универсальная дата-время события в миллисекундах\n        //   * ПолучитьДополнительныеПоля() - Соответствие - дополнительные поля события\n       \n        ФорматированноеСообщение = СобытиеЛога.ПолучитьСообщение();\n\n        Возврат ФорматированноеСообщение;\n    \n    КонецФункции\n    ```\n    ```bsl \n        Лог = Логирование.ПолучитьЛог(\"oscript.lib.test\");\n        Лог.УстановитьРаскладку(ЭтотОбъект);\n    ```\n    \nВ приведенной раскладке в сообщение помимо уровня и текста будет добавлено текущая дата.\n\n# Конфигурирование логов\n\nПредусмотрено изменение параметров логирования через специальный файл конфигурации, либо через переменную окружения.\nНезависимо от способа задания настроек, формат настроек остается одинаковым.\n\nФайл конфигурации должен лежать рядом со стартовым скриптом (см. метод *СтартовыйСценарий()*) и называться *logos.cfg*. Кроме того, настройки можно задать через переменную окружения LOGOS_CONFIG. Из-за неудобства ввода перевода строк в переменных окружения - в данном случае настройки надо разделять не переводом строк, а точкой-с-запятой. Формат настроек идентичен, независимо от способа задания конфига - в файле или в переменной.\n\nСледует учитывать, что переменная окружения имеет приоритет над файлом, и если задана она, то настройки берутся из нее, файл игнорируется.\n\n### Пример задания настроек через командную строку:\n```cmd\nset LOGOS_CONFIG=logger.oscript.lib.commands=DEBUG;logger.oscript.lib.cmdline=DEBUG\n```\n\n## Иерархия наследования настроек логов\nЕсли задать настройку:\n```cmd\nset LOGOS_CONFIG=logger.oscript.lib.query=DEBUG;\n```\nИ получить вот такие логи:\n```\nЛогОбновления = Логирование.ПолучитьЛог(\"oscript.lib.query.update\");\nЛогВыборки = Логирование.ПолучитьЛог(\"oscript.lib.query.select\");\n```\nТо оба лога унаследуют настройки ```oscript.lib.query```\n\n## Формат настроек логирования\n\nКаждая настройка задается в виде пары ```ключ=значение```. Причем, ключ является составным. Компоненты ключа разделены точками.\nПервым компонентом ключа идет *класс настройки*. Предусмотрены 2 класса - *logger* и *appender*. Первый отвечает за настройку конкретного журнала. Второй - за настройку способов вывода, используемых журналами.\n\n### Настройка журнала (класс logger)\n\n    logger.имя_журнала=Уровень[,СпособыВывода]\n\n* имя_журнала - это имя лога, как он описан в вызове метода ```Логирование.ПолучитьЛог();```, например, **oscript.lib.v8runner**.\n* СпособыВывода - это список произвольных имен способов вывода, которые привязаны к журналу. Конкретная настройка каждого из заявленных способов вывода выполняется в классе настроек *appender*.\n\nНапример, журнал **oscript.lib.v8runner** может быть настроен следующим образом:\n\n    logger.oscript.lib.v8runner=DEBUG, v8rdebug, console\n\n### Корневой журнал (логгер)\n\nВ классе настроек logger возможно указать специализированное имя ``rootLogger``. Настройки корневого логгера влияют на все прочие журналы. Это удобно, если вы хотите просто включить отладку по всем журналам или все журналы направить в файл.\n\nНапример:\n\n    logger.rootLogger=DEBUG\n\n### Настройка через переменные среды\n\nОбычная установка через командную строку, например, используя отдельный командный файл\n\n    set LOGOS_CONFIG=logger.rootLogger=DEBUG\n\n\nили\n\n    set LOGOS_LEVEL=DEBUG\n\nУстановка и немедленный запуск команды-скрипта через командную строку без создания командного файла\n\n    (LOGOS_LEVEL=DEBUG) \u0026\u0026 (любая команда)\n\nили\n\n    (set LOGOS_CONFIG=logger.rootLogger=DEBUG) \u0026\u0026 (любая команда)\n\nНапример:\n\n    (LOGOS_LEVEL=DEBUG) \u0026\u0026 (vanessa-runner help)\n\nили\n\n    (set LOGOS_CONFIG=logger.rootLogger=DEBUG) \u0026\u0026 (vanessa-runner help)\n\n### Настройка способа вывода (класс appender)\n\n    logger.oscript.lib.v8runner=DEBUG, v8rdebug, console\n    appender.v8rdebug=ВыводЛогаВФайл\n    appender.v8rdebug.level=DEBUG\n    appender.v8rdebug.file=/var/log/v8runner-debug.log\n    \n    appender.console=ВыводЛогаВКонсоль\n    appender.console.level=INFO\n\nВ приведенном примере для лога oscript.lib.v8runner установлен уровень Отладка и заявлено 2 способа вывода. Они названы v8rdebug и console (названия произвольные, т.е. здесь мы \"объявляем\" эти названия, придумав их самостоятельно, а ниже - по ним обращаемся к настройке логгера).\n\nДалее, в конфигурации указаны настройки заявленных способов вывода (аппендеров). Обязательным параметром является класс (тип языка), реализующий способ вывода. В данном примере указаны типы **ВыводЛогаВФайл** и **ВыводЛогаВКонсоль**.\n\n    // формат указания класса реализации\n    appender.имя_способа_вывода=Класс\n\nДля каждого класса можно установить собственный уровень вывода сообщений. В этом случае перед выводом сообщения система логирования будет фильтровать сообщения.\nДля установки нужно заполнить свойство `level`. Возможные значения для свойства - `DEFAULT`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICALERROR`, `DISABLE`\n\nНапример, в указанном выше примере для способа вывода `console` (который мы сами так назвали выше) установлен уровень вывода сообщений информации и более серьезных. Отладочные сообщения в эту консоль не выводятся.\nА вот для способа вывода `v8rdebug` (который мы тоже сами так назвали выше) установлен уровень вывода сообщений `Отладка`. Т.е. этим способом вывода будут выводиться все сообщения!\n\n    appender.v8rdebug.level=DEBUG\n    appender.console.level=INFO\n\nДля каждого класса могут потребоваться какие-то свои параметры. Например, класс ВыводЛогаВФайл требует задания свойства file. Свойства способа вывода задаются через точку от имени способа вывода:\n\n    // формат указания свойства\n    appender.имя_способа_вывода.свойство=значение\n\n## Примеры настройки\n\n## Я хочу включить отладочный лог приложения\n\nДля этого нужно включить уровень логирования DEBUG для всех логгеров приложения\n\n### С помощью файла logos.cfg\n\n    logger.rootLogger=DEBUG\n\n### С помощью переменной окружения LOGOS_CONFIG\n\n     set LOGOS_CONFIG=logger.rootLogger=DEBUG\n     \nОбратите внимание, значение переменной LOGOS_CONFIG это **то же самое, что** строки файла logos.cfg. Строки отделяются друг-от-друга точкой с запятой.\n    \n### С помощью переменной окружения LOGOS_LEVEL\n\nПеременная LOGOS_LEVEL является сокращенным способом доступа к настройке logger.rootLogger, для удобства \n\n    set LOGOS_LEVEL=DEBUG\n    \n## Я хочу выводить лог некоторой библиотеки connector в файл http.log\n\nДано: приложение SOME_APP, которое общается по сети с помощью библиотеки connector.\nПусть: известно, что библиотека connector пишет в лог с именем `oscript.lib.connector`\n\n### С помощью файла logos.cfg\n\n```\nlogger.oscript.lib.connector=INFO, foo\nappender.foo=ВыводЛогаВФайл\nappender.foo.file=/var/log/http.log\n```\n\nОбратите внимание, в первой строке объявлено, что логгер oscript.lib.connector связан с аппендером foo (название придумали сами, прямо тут). Далее, во второй строке указывается, что аппендер foo (который мы придумали) является классом `ВыводЛогаВФайл` и пишет в файл /var/log/http.log\n\n### С помощью переменной окружения LOGOS_CONFIG\n\nПри использовании переменной окружения мы должны просто повторить строки файла конфигурации, разделив их точкой-с-запятой.\n\n    set LOGOS_CONFIG=logger.oscript.lib.connector=INFO, foo;appender.foo=ВыводЛогаВФайл;appender.foo.file=/var/log/http.log\n    \nТаким образом, если у нас есть приложение, настройки логирования которого надо переопределить, мы должны создать рядом со стартовым скриптом приложения файл logos.cfg, либо (если не знаем где лежит этот файл или нет к нему доступа) создать переменную окружения LOGOS_CONFIG, написав в ней строки конфигурирования, разделив их точкой-с-запятой.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foscript-library%2Flogos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foscript-library%2Flogos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foscript-library%2Flogos/lists"}