Автор оригинала: FreeCodeCamp Community Member.
Gajus kuizinas.
Ноль-конфигурация, вне процессов транспортировки и придерживается двенадцати факторов
Последние 8 месяцев я создавал Go2cinema Отказ Это веб-приложение позволяет пользователям открывать ShowTimes. Они также могут забронировать билеты кино во всем мире.
Платформа выросла до +50 различных услуг. Услуги поддерживают агрегацию данных, нормализацию, валидацию, анализ, распределение, аннулирование и многое другое. Некоторые из этих услуг бегают в условиях высокой репликации в сотни.
Мне нужно было знать, когда все сломается. И мне нужно было уметь коррелировать журналы во всех этих услугах, чтобы определить проблему.
Мне нужен был журнал, который не существовал.
Существующие логики
Долгое время я был большим поклонником использования отлаживать . Отладка проста в использовании, работает в Node.js и браузерам, не требует конфигурации и быстро. Однако возникают проблемы, когда вам нужно анализировать журналы. Все, кроме однострочных текстовых сообщений не могут быть проанализированы безопасным способом.
Чтобы воспользоваться структурированными данными, я использовал Уинстон и Буниан . Эти пакеты отлично подходят для регистрации уровня начисления. Я предпочел Буньян из-за Программа Bunyan CLI используется для красивых журналов печати.
Однако эти пакеты требуют конфигурации уровня программы. При строительстве экземпляра регистратора необходимо определить транспорт и уровень журнала. Это делает их неподходящими для использования в коде, предназначенном для использования другими приложениями.
Тогда есть Pino Отказ Pino – это быстрый журнал JSON. Это программа CLI эквивалентна Bunyan. Это декурсирует транспортировки, и у него есть параметр Sane по умолчанию. Тем не менее, вам все еще нужно создать экземпляр регистратора регистратора на уровне приложения. Это делает его более подходящим для регистрации уровня нанесения, как Winston и Bunyan.
Мне нужен был логин, который:
- Разделяет код из конфигурации Вся конфигурация хранится в переменных среды
- Производит структурированные данные
- Разумные транспортировки
- Имеет Программа CLI
- Работает в Node.js и браузере
Другими словами, регистратор, который:
- Я могу использовать в приложении и в зависимости
- позволяет мне коррелировать журналы между основным приложенным кодом и код зависимости
- Хорошо работает с транспортом во внешних процессах
… и это должно быть громко когда вещи действительно ломаются.
Roarr Это регистратор.
Строгий API.
Logger должен иметь API, который просто запомнить и производит предсказуемые результаты. Roarr достигает этого, ограничивая поверхность API.
Конфигурация
Регистрация Roarr отключена по умолчанию. Чтобы включить журнал, вы должны запустить программу с переменной средой Roarr_Log установить правда :
ROARR_LOG=true node ./index.js
Все Конфигурация Roarr делается с использованием переменных среды. Разработчик не может отключить журнал или установить уровень ведения журнала на уровне приложения. Это хорошая вещь – фильтрация, форматирование и журналы дополнения принадлежат к вне процессов транспорта . Это гарантирует, что вам никогда не нужно касаться кода, чтобы изменить поведение журнала.
Функция регистратора
Roarr API ограничен двумя параметрами (плюс printf Аргументы форматирования).
- Первый параметр может быть либо строкой (сообщение), либо объектом. Если первый параметр является объектом (контекстом), второй параметр должен быть строкой (сообщение).
- Аргументы после того, как параметр сообщения используется для включения форматирования сообщений PrintF. Распечатать аргументы должны быть примитивного типа (
String | Номер | Boolean | NULL). Может быть до 9 аргументов PrintF (или 8, если первый параметр – это объект контекста).
На практике это переводится на следующее использование:
import log from 'roarr';log('foo');log('bar %s', 'baz');const debug = log.child({ level: 'debug'});debug('qux');debug({ quuz: 'corge'}, 'quux');Параметр контекста содержит произвольные пользовательские данные, используемые для идентификации контекста, в котором был создан сообщение журнала. Он может содержать имя приложения, имя пакета, идентификатор задачи, имя хоста, имя программы и другие данные.
Это производит вывод:
{"context":{},"message":"foo","sequence":0,"time":1506776210000,"version":"1.0.0"}{"context":{},"message":"bar baz","sequence":1,"time":1506776210000,"version":"1.0.0"}{"context":{"level":"debug"},"message":"quux","sequence":2,"time":1506776210000,"version":"1.0.0"}{"context":{"level":"debug","quuz":"corge"},"sequence":3,"message":"quux","time":1506776210000,"version":"1.0.0"}Этот вывод предназначен для потребления транспортных перевозок.
Осмотрите журналы
Чтобы проверить журналы по времени разработки, используйте Roarr Beay-Print программа.
Выходной вывод о том, что программа CLI Print Print производит выглядит так:
Программа CLI опирается на набор Конвенции Для структурирования данных.
Программа Roarr CLI имеет пару других команд и варианты. Смотри roarr. --help для дополнительной информации.
Узор использования
Чтобы избежать дублирования кода, вы можете использовать Синглтон Узор Чтобы экспортировать экземпляр регистратора с предопределенными свойствами контекста. Например, описывая приложение.
Использование Roarr в приложении
Я рекомендую создать файл Logger.js В каталоге базового проекта. Вы можете использовать этот файл для создания дочернего экземпляра Roarr с параметрами контекста, описывающими проект и инициализацию.
/** * @file Example contents of a Logger.js file. */
import Roarr from 'roarr';import ulid from 'ulid';
// Instance ID is useful for correlating logs in high concurrency environment.//// See `roarr augment --append-instance-id` option as an alternative way to// append instance ID to all logs.const instanceId = ulid();
// The reason we are using `global.ROARR.prepend` as opposed to `roarr#child`// is because we want this information to be prepended to all logs, including// those of the "my-application" dependencies.global.ROARR.prepend = { ...global.ROARR.prepend, application: 'my-application', instanceId};export default Roarr.child({ // .foo property is going to appear only in the logs that are created using // the current instance of a Roarr logger. foo: 'bar'});Используя Roarr в зависимости
Если вы разрабатываете код, предназначенный для потребления других приложений и модулей, вы должны избегать использования Глобальный. Roarr. . Хотя есть Допустимые случаи использования Отказ
Вы все равно должны начать проект, определив Logger.js Файл и использовать log.child. вместо.
/** * @file Example contents of a Logger.js file. */
import Roarr from 'roarr';
export default Roarr.child({ domain: 'database', package: 'my-package'});Roarr не имеет зарезервированных имен контекстных свойств. Тем не менее, я поощряю использование Конвенции Отказ
Roarr Beay-Print CLI программа использует имена контекстных свойств, предложенных в конвенциях. Это будет довольно печатать журналы для целей инспекции разработчика.
Фильтрация журналов
Roarr предназначен для печати все или без журналов. Обратитесь к Roarr_Log Документация переменной среды.
Чтобы фильтровать журналы, необходимые для использования процессора JSON, например JQ Отказ
JQ позволяет фильтровать сообщения JSON, используя Выберите (boolean_expression) :
ROARR_LOG=true node ./index.js | jq 'select(.context.logLevel == "warning" or .context.logLevel == "error")'
Результатом является единственное сообщение журнала, которое имеет либо «предупреждение», либо «ошибка» уровня журнала. Вы можете комбинировать JQ с Roarr CLI Program, чтобы сосредоточиться на конкретном сообщении об ошибке:
ROARR_LOG=true node ./index.js | jq 'select(.context.package == "usus")' | roarr pretty-print
Манипулирование контекстом сообщения журнала глобально
К настоящему времени вам, вероятно, есть висит, что является журналом сообщение «контекст». Это объект клавишного значения, определяющая переменные среды во время регистрации сообщения.
В некоторых случаях может быть полезно для получения свойств объекта контекста глобально для всех сообщений во время выполнения. Например, у вас есть задача запущенной программы И вы хотите связать все журналы, которые напечатали во время выполнения задач.
Вы можете сделать это, используя Global.roarr.Prepend:
import log from 'roarr';import foo from 'foo';const taskIds = [ 1, 2, 3];for (const taskId of taskIds) { global.ROARR = global.ROARR || {}; global.ROARR.prepend = { taskId }; log('starting task ID %d', taskId); // In this example, `foo` is an arbitrary third-party dependency that is using // roarr logger. foo(taskId); log('successfully completed task ID %d', taskId); global.ROARR.prepend = {};}Производит вывод:
{"context":{"taskId":1},"message":"starting task ID 1","sequence":0,"time":1506776210000,"version":"1.0.0"}{"context":{"taskId":1},"message":"foo","sequence":1,"time":1506776210000,"version":"1.0.0"}{"context":{"taskId":1},"message":"successfully completed task ID 1","sequence":2,"time":1506776210000,"version":"1.0.0"}[...]Если вы используете центральный Журнал Агрегатор Вы можете легко найти все журналы, связанные с определенной задачей. Это полезно, если вы расследуете ошибку, которая рано прекратила задачу.
Транспорт
В большинстве регистрации библиотек перенос работает в процессе для выполнения операции с окончательной линией журнала. Например, транспорт может отправить линию журнала на стандарт Syslog Сервер после обработки и переформатируя его.
Roarr не поддерживает вспомогательные транспорта, потому что узел процессы являются однопоточными процессами. Roarr разгружает обработку журналов к внешним процессам, поэтому можно использовать возможности для резьбы OS или других процессоров.
В зависимости от вашей конфигурации рассмотрите один из следующих транспортных перевозок:
- Beats Для агрегации на уровне процесса Написано в пути
- логин Для агрегации на уровне процесса Написано в JavaScript
- Fluentd Для агрегирующих журналов на уровне оркестрации контейнера, такими как Kubernetes Написано в Ruby.
В случае FluentD и Kubernetes, агрегируя все журналы к Elasticsearch так же просто, как создание единого Daemonset Отказ
Будущее Ройрр
Roarr CodeBase не сложен. Успех проекта, такого как Roarr, сильно зависит от эффекта масштаба. Чем больше зависимостей используют Roarr, тем больше его значение обеспечивает.
Включение журнала позволяет мгновенно собрать все данные о приложениях. Их компоненты, необходимые для мониторинга здоровья приложений и вопросов трассировки.
В некотором смысле мне повезло. В течение многих лет я разработал абстракцию практически для каждого компонента, который составляет My Node.js и приложения браузера.
Они варьируются от Клиент базы данных , Дом Оценщик , HTTP Server Manager Manager , и так далее. Это позволяет мне быстро пожинать преимущества пакета, такого как Roarr.
Время покажет, принимает ли остальную часть сообщества Roarr с равной страстью.
Как насчет имени?
Я получил некоторую первоначальную критику о использовании универсального, «клевного» имени, такого как «Ройрр». Основная причина выбора имени – идентифицировать пакет как громко Отказ Журналы Roarr не могут быть подавлены, как рев тигра.
С практической точки зрения, «Roarr» – это безопасный срок Греп и зарезервировать в глобальной среде.
Roarr!
Я стандартизирую Roarr Во всех приложениях Node.js и пакеты, которые я поддерживаю.
Я ожидаю, что это улучшит мою способность быстро обнаруживать проблемы. Это поможет мне перенастроить настройки журнала существующих приложений – без изменения исходного кода для настройки объемов журнала. И это улучшит мой повседневную опыт журналов приложений хвостовой связи.
Регистрация является одним из самых страшных частей разработки приложений. Ройрр делает его менее страшно.
Вы любите читать, я люблю писать
Вы можете поддержать мои Работа с открытым исходным кодом И я пишу технические статьи через Купи мне кофе и Патен . У тебя будет моя вечная благодарность?
Оригинал: “https://www.freecodecamp.org/news/roarr-the-perfect-json-logger-node-js-and-browser-935180bda529/”