Архитектура и системы плагинов LogDoc

Во вводной статье мы познакомили вас с основными концепциями LogDoc. Теперь настала пора рассказать о том как устроен LogDoc изнутри и какие возможности в нём есть для расширения функционала.

Принципиальная архитектура LogDoc одинакова для всех версий: блок приёмников (улья и соты) отвечает за приём сырых данных, их структуризацию, передачу в хранилище (ClickHouse, при наличии) и передачу в фильтры. Блок фильтров анализирует структуры, совпадения передаются в «ядро». Ядерная группа занимается маршрутизацией, циклами жизни и разграничением доступа. Поступившие структуры направляются своим потребителям (пользователи, объекты сторожей, сторонние ИС) . Объекты сторожей, в свою очередь, при накоплении счётчиков и/или соблюдении условий сценариев, обращаются к блоку «плагинов вывода», которые непосредственно осуществляют «реакции» – исполняют некие действия, заложенные в их бизнес-логике. Все версии поддерживают расширение функционала через две системы плагинов – приёмники (sink-плагины) и реакции (pipe-плагины) .

Portable версия лишена баз данных – то есть, отсутствует хранилище ClickHouse и БД Postgres. Все блоки объединены в один физический дистрибутив. Используется в виде самостоятельного веб-приложения на базе Play framework. Для запуска требуется JRE версии 11 или выше. Отсутствует разграничение доступа. Не масштабируется.

Community версия реализует полную архитектуру, но также объединена в один физический дистрибутив в виде веб-приложения на базе Play framework. Для запуска

требуется JRE версии 11 или выше. Не масштабируется. Связь с хранилищем ClickHouse – по HTTP. Связь с БД Postgres – JDBC.

Pro версия реализует полную архитектуру. Блоки приёмников и ядра разделены структурно и физически. Блок приёмников является консольным java-приложением. Для запуска необходим JRE версии 8 или выше. Ядерный блок является веб-приложением на базе Play framework. Для запуска требуется JRE версии 11 или выше. Обе части реализуют концепцию SOA, являются stateless приложениями и, следовательно, могут быть масштабированы в любых пропорциях относительно друг друга. БД Postgres, необходимая для работы ядерного блока, может быть как единой для всех экземпляров ядра, так и персональной для каждого экземпляра (зависит от характера использования) . Хранилище ClickHouse при этом должно быть единым для всего кластера LogDoc. Между всеми компонентами должна быть обеспечена адресная достижимость. Связь между компонентами приёмника и ядра происходит по tcp/ip, по собственному внутреннему протоколу. Связь с хранилищем ClickHouse – по HTTP. Связь с БД Postgres – JDBC. Опционально, в ядерном блоке может быть использован внешний сервис службы аутентификации и поиска учётных записей (например, корпоративный LDAP) .

LogDoc обеспечивает приём данных по протоколам tcp/ip и udp. (Http как частный случай tcp/ip соединения). Движок занимается обслуживанием сокетов и порционным чтением данных из них, преобразование этих данных в структуры для анализа и хранения – задача sink-плагинов. Один плагин может осуществлять преобразование любого количества форматов и протоколов. Объект плагина - stateful singleton, который рождается один раз при инициализации LogDoc и живёт до завершения работы всего приложения. Сокеты рождаются движком, согласно объявленным типам поддержки, затем данные из сокетов поступают плагину на вход массивами различного размера (сколько прочиталось); плагин, по накоплению полной структуры, должен передать её в движок.

Для внедрения своего sink-плагина достаточно реализовать интерфейс org.logdoc.sdk.SinkPlugin из нашего SDK, упаковать классы в jar и положить в директорию плагинов (по умолчанию - ./plugins/sink в рабочей директории logdoc)

Из коробки мы предоставляем 5 плагинов для поддержки 7 входящих типов данных:

Наши плагины – open source, их можно использовать в качестве примера или модифицировать для своих нужд: https://github.com/LogDoc-org/sink-plugins

Также из коробки мы предоставляем поддержку logs over http, функционально повторяющую возможности sentry, для мобильных приложений и вебприложений в части фронтенда (js), но это не является частью системы sink-плагинов.

Наши плагины – open source, их можно использовать в качестве примера или модифицировать для своих нужд: https://github.com/LogDoc-org/sink-plugins

Протокол бинарный, big-endian. Заголовок перед каждым пакетом: ‘\006\003’

Каждая отдельная структура LogDoc состоит из неопределённого количества пар ключ/значение (как переменные environment). Однако, отличие от пар environment, значения могут содержать NUL-ы и бинарные данные. Ключи не могут содержать символ '=', символы перевода строки, любые другие управляющие символы и не-ASCII символы) и не могут быть пустыми.

Каждая пара ключ/значение сериализуется одним из двух способов:

В первом случае между ключом и значением вставляется символ `=`, а в конце добавляется символ перевода строки `\n` (ASCII код 10). То есть, например для ключа `FOO` и значения `BAR` сериализованное значение будет: `F,O,O,=,B,A,R,\n`

Второй метод используется, когда значение содержит байт `\n`. В этом случае ключ сериализуется как есть, к нему добавляется байт `\n`, затем добавляется big-endian unsigned 32bit integer, кодирующий длину значения, затем само значение и в конце добавляется ещё один байт `\n`. То есть, например для той же пары `FOO`:`BAR` сериализация этим способом будет выглядеть так: `F,O,O,\n,\000,\000,\000,\003,B,A,R,\n`

Если значение в паре ключ/значение содержит символ перевода строки `\n`, то эта пара обязательно должна быть сериализована вторым способом. В ином случае метод сериализации остаётся на выбор исполнителя. Однако, рекомендуется использовать первый метод везде, где это возможно - это облегчает дебаг и визуальный просмотр структур.

Стоит обратить внимание на несколько ключей, которые имеют особое значение в логике LogDoc: `trcv, ip`. Эти ключи неявно указываются библиотеками LogDoc и в дальнейшем используются для обеспечения бизнес-логики при обработке структур данных. В абсолютном большинстве случаев, даже если эти ключи используются клиентами - они будут перезаписаны модулями LogDoc служебными значениями.

Самая важная пара, которая должна присутствовать в каждой отдельной структуре это пара с ключом `msg`. Значение из этой пары считается телом структуры и без неё структура в целом будет проигнорирована.

Менее значимые, не требуемые, но ожидаемые ключи:

- `tsrc`: локальное время создания структуры, в формате `ггммддччммссннн` - `pid`: уникальный ID процесса - родителя структуры

- `src`: имя логгера (инструмента) в формате *package name conventions* ([a-z0-9.-]+) - `lvl`: уровень структуры - один байт; от 0 до 6 [DEBUG, INFO, LOG, WARN, ERROR, SEVERE, PANIC]

- `app`: имя приложения - родителя структуры. Любое

самоназв[ld_format.md](ld_format.md)ание.

Эти пары будут использованы для показа и обработки структур, при наличии.

LogDoc предоставляет возможность создания фильтров по структурам, которые приходят из внешних источников. Срабатывание фильтра – это учитываемое событие, за ним могут следовать либо инкрементация некоего счётчика, либо ожидание следующего события, по другому фильтру, что тоже будет событием. Достижение счётчиком определённого порога – это также событие. И пороговые значения нескольких счётчиков в течение определённого временного интервала – тоже событие. Группа подобных событий, объединённая с определённой целью – это «сторож», который вызывает какие-то определённые «реакции», т.е. действия в следствие произошедших событий. Каждая реакция – это результат работы одного pipe-плагина.

Для внедрения своего pipe-плагина достаточно реализовать интерфейс org.logdoc.sdk.PipePlugin из нашего SDK, упаковать классы в jar и положить в директорию плагинов (по умолчанию - ./plugins/pipe в рабочей директории logdoc)

Из коробки мы предоставляем три вида реакций:

Наши плагины – open source, их можно использовать в качестве примера или модифицировать для своих нужд: https://github.com/LogDoc-org/pipe-plugins

В LogDoc определено два вида пользователей – привилегированные (администрация) и обычные.

Для того, чтобы избежать необходимости назначать ограничения и разрешения для каждого пользователя индивидуально, в LogDoc есть «группы доступа».

Каждая группа – суть набор разрешений и ограничений, транслируемый на каждого участника группы. Разрешения – это 4 флага, маркирующие возможность пользоваться четырьмя блоками LogDoc – функционал «Поток» – просмотр поступающих логов в

реальном времени; функционал «Сторож» – возможность создавать фильтры с последующими реакциями; функционал «История» – просмотр исторических записей из хранилища; функционал «http-точки» – возможность приёма данных из мобильных и веб приложений через http нa отдельных ендпоинтах. Но самым важным свойством группы является возможность определить фильтр(ы), которые будут автоматически применяться ко всем действиям (выборкам, фильтрам и т.д.) всех членов этой группы. Фильтры всех групп складываются, то есть применяются с операндом AND. Разрешительные атрибуты всех групп применяются до получения положительного результата, то есть – если хоть одна группа пользователя разрешает ему использование функционала «Сторож», то считается, что пользователю данный функционал разрешён, не смотря на то, что все остальные группы его не разрешают.

Каждый пользователь может принадлежать к произвольному количеству групп, в том числе – ни к одной.

В Pro версии мы предоставляем возможность использования корпоративного сервиса авторизации, аутентификации и поиска пользователей – например, через через LDAP, что облегчит бесшовную интеграцию с вашей инфраструктурой. То есть, вам не придётся заводить всех своих пользователей в LogDoc руками, дублируя учётные записи.

На этом вторая статья закончена. Мы постарались кратко, но точно обрисовать все основные возможности LogDoc. Искренне надеемся, что продукт будет вам полезен. Также мы будем рады найти коммерческих партнёров для взаимовыгодного сотрудничества.

Пишите нам:
по общим вопросам: info@logdoc.org
по коммерческим: biz@logdoc.org
telegram: https://t.me/logdoc