Перейти к основному содержимому
Версия: 4.6.X

Файловый коллектор

Назначение

Файловый коллектор предназначен для сбора событий из текстовых файлов журналов с локальной машины коллектора или с удалённого узла по протоколу SFTP. Для каждой новой строки отслеживаемого файла формируется событие безопасности с сохранением исходного текста в поле Raw.

Коллектор применяется в следующих сценариях:

  • Источник событий записывает журналы только в локальные файлы и не поддерживает отправку по Syslog.
  • Требуется собирать журналы прикладного программного обеспечения, веб-серверов, СУБД, контейнерных платформ.
  • Необходимо обработать единовременно выгруженный файл журналов.

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

Установка коллектора

Предварительные условия:

  • наличие лицензии (разрешения) на использование Файлового коллектора (см. «О программе»);
  • сетевая доступность сервера KOMRAD с узла, на который устанавливается коллектор;
  • для сбора с удалённых узлов — поддержка протокола SFTP на источнике и учётная запись с правом чтения собираемых файлов.

Порядок установки:

  1. Перенести deb-пакет komrad-file-collector*.deb из дистрибутива KOMRAD на узел, где будет работать коллектор.

  2. Установить пакет:

    sudo dpkg -i ./komrad-file-collector*.deb
  3. Открыть файл конфигурации:

    sudo nano /etc/echelon/komrad/komrad-file-collector.yaml
  4. Указать адрес шины событий KOMRAD в параметре bus.servers:

    bus:
    servers:
    - nats://<IP_KOMRAD>:3490
  5. Сохранить файл и перезапустить службу коллектора:

    sudo systemctl restart komrad-file-collector.service
  6. После запуска коллектор отобразится в списке коллекторов в веб-интерфейсе.

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

/etc/echelon/komrad/komrad-file-collector.yaml
### schema: komrad/komrad-file-collector/4.1.33
# Идентификатор предприятия
tenant_id: 75
# Идентификатор установки
setup_id: komrad-production
# Метка безопасности, аналог Oracle Security Label
sl: 715
bus:
servers:
- nats://10.0.5.197:3490
user: komrad
password: pass
user-credentials: ""
tls:
disable: false
ServerName: ""
TrustedCA: /var/lib/echelon/komrad/certs/ca.pem
Cert: /var/lib/echelon/komrad/certs/client.pem
CertKey: /var/lib/echelon/komrad/certs/client-key.pem
system-pool: false
min-version: "1.3"
client-auth: require-and-verify-client-cert
tuning:
# Время ожидания при установке соединения.
connect-timeout: 10s
# Максимальное количество попыток повторного подключения.
max-reconnects: 1000000
# Максимальное время ожидания ответа.
max-wait: 0s
# Период отправки клиентских команд ping.
ping-interval: 2m
# Максимальное количество запросов ping без ответа сервера,
# после которого соединение закрывается.
max-pings-outstanding: 2
# Максимальное количество одновременных асинхронных публикаций.
publish-async-max-pending: 0
# Интервал между попытками переподключения.
reconnect-interval: 5s
# Время ожидания между попытками повторного подключения.
reconnect-wait: 1s
# Переходить в состояние повторного подключения,
# если первичное подключение не удалось.
retry-on-failed-connect: false
# Таймаут между попытками перезапуска коллектора при неустойчивой связи
# с центральным сервером KOMRAD.
restart-timeout: 1s
# local_ip: 10.0.0.1
# Настройки пакетной отправки событий. Накопление событий в пакеты
# повышает пропускную способность. Увеличение `timeout` до 3s и `limit`
# до 20000 позволяет достигать 100 000 EPS.
batching:
# Предельный интервал накопления пакетов. По умолчанию — 1 секунда.
timeout: 1s
# Предельное количество событий в пакете. По умолчанию — 100.
limit: 1000
# Настройки write-ahead-log (WAL). При разрыве связи с сетью события
# записываются на диск в сжатом виде, после восстановления соединения
# отправляются в шину событий KOMRAD.
# Объём свободного пространства на узле коллектора необходимо контролировать.
wal:
# Путь до каталога WAL. Если не указан, используется каталог по умолчанию:
# Windows: C:\Program Files\Echelon\komrad\<name>-collector\.wal
# Linux: /var/lib/echelon/komrad/<name>-collector/.wal
# При установке нескольких одинаковых коллекторов на один хост необходимо
# указывать разные пути; пути не должны быть вложенными друг в друга.
path: /var/lib/echelon/komrad/komrad-file-collector/.wal
# Режим оптимизации работы с памятью. Изменять только по рекомендации
# службы поддержки.
no-copy: true
# Размер одного сегмента WAL. По умолчанию — 4 МБ. Изменять только
# по рекомендации службы поддержки.
segment-size: 4MB
# Максимальная длина WAL. Значение 0 означает отсутствие ограничения.
max-length: 0
# Настройки вывода логов приложения. Поддерживается одновременный вывод
# в несколько целей: файл, системный журнал ОС, консоль, syslog.
#
# Пример вывода в консоль для режима отладки:
# - filename: stdout
# format: color
# filter: ""
# levels: [all]
#
# Пример вывода в файл с ротацией (старые файлы не удаляются автоматически,
# использование диска необходимо контролировать):
# - filename: "/var/log/echelon/komrad/service.log"
# format: json
# filter: ""
# levels: [info, error, warn, panic, fatal]
#
# Пример отправки критических сообщений в журнал Windows. Уровни info,
# warn, debug, error в windowseventlog включать не рекомендуется
# (отрицательно влияет на быстродействие и доступность узла):
# - filename: windowseventlog
# format: json
# levels: [panic, fatal]
log:
- filename: systemd/journal
format: json
filter: ""
levels:
- info
- error
- panic
- fatal
- warn
# Настройки дискового хранилища конфигурационных данных коллектора.
storage:
# Путь до каталога хранилища. Если не указан, используется каталог
# по умолчанию:
# Windows: C:\Program Files\Echelon\komrad\<name>-collector\.storage
# Linux: /var/lib/echelon/komrad/<name>-collector/.storage
# При установке нескольких одинаковых коллекторов на один хост необходимо
# указывать разные пути; пути не должны быть вложенными друг в друга.
path: /var/lib/echelon/komrad/komrad-file-collector/.storage
compress: false
# Включить синхронную запись каждого результата на диск.
# По умолчанию отключено.
sync-writes: false
# Путь к базе данных GeoIP.
geo-ip:
path: /var/lib/echelon/komrad/komrad-file-collector/geoip/db.mmdb
# Проверка корректности базы GeoIP при инициализации. Длительность —
# от 20 секунд до 2 минут в зависимости от ресурсов и размера базы.
# По умолчанию отключена.
verify-on-start: false
# Отключение записи исходного текста события в поле Raw.
# Большинство требований регулятора требуют сохранять исходный текст
# события. Сохранение увеличивает размер БД в 2–10 раз.
# Для коллекторов Файловый и Syslog отключение записи в Raw невозможно:
# исходный текст события является единственным источником данных.
disable-raw-field: false
# Использовать при работе только в локальном автономном режиме.
offline: false
plugins: []
events_file: ""

Подключение источника событий

Расположение в веб-интерфейсе: Управление ⇒ Настройки коллекторов ⇒ Файловый коллектор.

Параметры подключения

  1. Открыть карточку файлового коллектора.
  2. На вкладке «Источники» нажать «Добавить» — откроется форма создания нового источника.
  3. На вкладке «Подключение» указать:
    • Название — имя узла-источника.
    • Описание — произвольное описание.
    • ПротоколSFTP для удалённого узла или Локальная машина для сбора с того же узла, где работает коллектор.
    • Актив — IP-адрес источника (только для SFTP).
    • Авторизация — порт, логин и пароль учётной записи. Поддерживается авторизация по приватному ключу (сертификату); копию ключа необходимо поместить в каталог $HOME/.ssh пользователя, от имени которого запущен коллектор.
примечание

Учётная запись, используемая для подключения, должна иметь право чтения собираемых файлов на стороне источника.

Сбор файлов и папок

На вкладке «Сбор событий» добавляются пути к собираемым файлам. Поле Путь принимает как полное имя файла, так и шаблон с подстановочными символами — коллектор раскрывает шаблон при каждом обходе каталога и подхватывает файлы, появившиеся после запуска источника.

Поддерживаемые подстановочные символы:

СимволНазначение
*Любая последовательность символов в пределах сегмента
?Один любой символ
[…]Один символ из указанного набора
**Рекурсивный обход вложенных каталогов

Примеры:

/var/log/syslog # один конкретный файл
/var/log/*.log # все файлы с расширением .log в каталоге
/var/log/auditd-*.log # файлы по префиксу имени
/var/log/**/*.log # рекурсивный обход вложенных каталогов
/var/log/app-?.log # app-1.log, app-2.log, app-x.log и т.п.

Рекурсивный обход (**) выполняется на глубину до 8 уровней. Раскрытие шаблона ** включено по умолчанию через параметр recursiveGlob: true в дополнительных параметрах сбора.

Когда один шаблон захватывает больше файлов, чем требуется, дополнительная фильтрация выполняется регулярными выражениями в параметрах includeFiles и excludeFiles (см. раздел «Дополнительные параметры сбора»). Например, для отбора файлов по расширению:

{
"fileWatcher": {
"scanner": {
"includeFiles": ["\\.log$", "\\.txt$"],
"excludeFiles": ["\\.gz$", "\\.tmp$"]
}
}
}

Дополнительно для каждого пути в карточке источника задаются:

  • Включить сбор — флаг активации пути; неактивные пути игнорируются.
  • Игнорировать файлы старше — пропускать файлы, время последнего изменения которых раньше указанной длительности или абсолютной метки времени. Применяется к первому запуску — ранее необработанные старые файлы не будут прочитаны.

После сохранения настроек источника коллектор необходимо запустить (или перезапустить, если он уже был запущен). События, поступающие от источника, отображаются в разделе События ⇒ События в реальном времени.

предупреждение

При использовании шаблонов следует избегать перекрывающихся путей в разных источниках одного коллектора — один и тот же файл будет прочитан дважды, события продублируются.

Дополнительные параметры сбора

Расширенные параметры задаются JSON-документом на отдельной вкладке карточки источника. Документ соответствует proto-схеме FilestreamConfig (echelon.komrad.collector.v2.FilestreamConfig): имена полей в camelCase, значения перечислений — строковые константы вида ENCODING_*, LINE_TERMINATOR_*, PARSER_KIND_*, MULTILINE_TYPE_*, длительности — строки ISO-8601 ("5s", "10s", "0s").

Полный пример со значениями по умолчанию:

{
"id": "",
"reader": {
"encoding": "ENCODING_UNSPECIFIED",
"excludeLines": [],
"includeLines": [],
"lineTerminator": "LINE_TERMINATOR_AUTO",
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_MULTILINE",
"multiline": {
"match": "after",
"pattern": "",
"flushPattern": "",
"countLines": 1,
"type": "MULTILINE_TYPE_COUNT_MODE",
"negate": false,
"skipNewLine": false,
"maxLines": null,
"timeout": null
}
}
]
}
},
"close": {
"onStateChange": {
"checkInterval": "5s",
"inactive": "10s",
"removed": true,
"renamed": false
},
"reader": {
"afterInterval": "0s",
"onEof": false
}
},
"fileWatcher": {
"scanner": {
"symlinks": null,
"recursiveGlob": true,
"excludeFiles": [],
"includeFiles": []
}
},
"alertFileChanges": true
}

Кнопка «Проверить» на вкладке выполняет валидацию JSON-документа без сохранения. Кнопка «Сохранить» применяет конфигурацию к источнику.

Идентификатор (id)

ПараметрТипПо умолчаниюНазначение
idstring""Внутренний идентификатор конфигурации потока. Заполняется автоматически и сохраняется между сеансами для сопоставления состояний отслеживаемых файлов.

Чтение файла (reader)

ПараметрТипПо умолчаниюНазначение
encodingenumENCODING_UNSPECIFIEDКодировка файла. Допустимые значения: ENCODING_UNSPECIFIED (UTF-8), ENCODING_PLAIN, ENCODING_UTF8, ENCODING_GBK, ENCODING_ISO8859_1, ENCODING_ISO8859_5, ENCODING_KOI8R, ENCODING_CP866, ENCODING_MACINTOSH, ENCODING_WINDOWS1250, ENCODING_WINDOWS1251, ENCODING_WINDOWS1256, ENCODING_UTF16BOM.
excludeLinesstring[][]Регулярные выражения. Строки, соответствующие любому выражению, отбрасываются до отправки в шину событий.
includeLinesstring[][]Регулярные выражения. При непустом списке сохраняются только строки, соответствующие хотя бы одному выражению. Если заданы оба списка, includeLines применяется первым.
lineTerminatorenumLINE_TERMINATOR_AUTOРазделитель строк. Допустимые значения: LINE_TERMINATOR_AUTO, LINE_TERMINATOR_LINE_FEED, LINE_TERMINATOR_VERTICAL_TAB, LINE_TERMINATOR_FORM_FEED, LINE_TERMINATOR_CARRIAGE_RETURN, LINE_TERMINATOR_CARRIAGE_RETURN_LINE_FEED, LINE_TERMINATOR_NEXT_LINE, LINE_TERMINATOR_LINE_SEPARATOR, LINE_TERMINATOR_PARAGRAPH_SEPARATOR, LINE_TERMINATOR_NULL_TERMINATOR.
parsersobjectсм. нижеЦепочка парсеров, применяемых к прочитанным строкам.

Парсеры (reader.parsers.parsers[])

reader.parsers.parsers — упорядоченный массив парсеров. Каждый элемент описывается типом (kind) и блоком конфигурации соответствующего типа. Поддерживаемые типы:

Значение kindНазначение
PARSER_KIND_MULTILINEОбъединение нескольких строк в одно событие. Настраивается полем multiline (см. ниже).
PARSER_KIND_NDJSONРазбор построчного JSON. Каждая строка интерпретируется как JSON-документ.
PARSER_KIND_CONTAINERРазбор журналов контейнеров (Docker, CRI).

В текущей версии proto-схемы UI-редактор передаёт настройки только для парсера multiline. Параметры ndjson и container принимаются со значениями по умолчанию.

multiline — объединение многострочных событий
ПараметрТипПо умолчаниюНазначение
typeenumMULTILINE_TYPE_COUNT_MODEРежим объединения: MULTILINE_TYPE_PATTERN_MODE — по регулярному выражению, MULTILINE_TYPE_COUNT_MODE — по количеству строк, MULTILINE_TYPE_WHILE_PATTERN_MODE — пока строки соответствуют шаблону.
patternstring""Регулярное выражение для режимов PATTERN_MODE и WHILE_PATTERN_MODE.
negateboolfalseИнвертирование результата проверки pattern.
matchstringafterСтратегия объединения строк: after — относительно последнего совпадения, before — относительно следующего совпадения.
countLinesint321Количество строк, объединяемых в одно событие (для COUNT_MODE).
maxLinesint32 | nullnullВерхний предел числа строк в одном событии.
timeoutduration | nullnullТаймаут ожидания строк, после которого накопленные строки отправляются как событие. Формат — строка ISO-8601 ("5s").
flushPatternstring""Регулярное выражение, завершающее многострочное событие. При совпадении накопленные строки отправляются немедленно.
skipNewLineboolfalseОбъединять строки без разделителя \n.

Завершение работы обработчика (close)

ПараметрТипПо умолчаниюНазначение
close.onStateChange.checkIntervalduration"5s"Периодичность проверки состояния файла (изменение размера, переименование, удаление).
close.onStateChange.inactiveduration"10s"Таймаут закрытия дескриптора при отсутствии изменений файла.
close.onStateChange.removedbooltrueЗакрывать обработчик при удалении файла.
close.onStateChange.renamedboolfalseЗакрывать обработчик при переименовании файла.
close.reader.afterIntervalduration"0s"Таймаут закрытия обработчика с момента его запуска. "0s" — отключено.
close.reader.onEofboolfalseЗакрывать обработчик при достижении конца файла. Возможна потеря данных, если файл будет дописан после закрытия.

Обнаружение новых файлов (fileWatcher.scanner)

ПараметрТипПо умолчаниюНазначение
fileWatcher.scanner.symlinksbool | nullnullОбрабатывать символические ссылки наряду с обычными файлами.
fileWatcher.scanner.recursiveGlobbool | nulltrueРаскрывать шаблон ** в путях для рекурсивного обхода вложенных каталогов. Глубина — до 8 уровней.
fileWatcher.scanner.excludeFilesstring[][]Регулярные выражения. Файлы, имя которых соответствует хотя бы одному выражению, игнорируются.
fileWatcher.scanner.includeFilesstring[][]Регулярные выражения. При непустом списке обрабатываются только файлы, имя которых соответствует хотя бы одному выражению. Удобно для отбора по расширению: ["\\.log$"].

Уведомления об изменении файлов (alertFileChanges)

ПараметрТипПо умолчаниюНазначение
alertFileChangesbooltrueФормировать события при создании, перемещении и удалении файлов в отслеживаемом каталоге.
примечание

Параметры идентификации файлов (fileIdentity), ротации, лимита обработчиков, очистки реестра и метаданных событий не вынесены в текущую proto-схему FilestreamConfig и используют значения по умолчанию из backend-конфигурации коллектора.

Примеры конфигурации источников

Ниже приведены типовые конфигурации источников для распространённых сценариев сбора. В каждом примере указано значение поля Путь на вкладке «Сбор событий» и JSON-документ для вкладки «Дополнительные параметры сбора». Поля, не упомянутые в примере, остаются со значениями по умолчанию.

Сценарий 1. Системные журналы Linux из одного каталога

Сбор журналов аутентификации и системных событий с локальной машины коллектора. Файлы записываются построчно в UTF-8, специальной обработки не требуют.

Поле Путь:

/var/log/auth.log
/var/log/syslog

Дополнительные параметры — значения по умолчанию.

Сценарий 2. Рекурсивный сбор журналов микросервисов

Несколько прикладных служб записывают журналы в подкаталоги общего каталога (/var/log/apps/<service>/...). Состав каталогов меняется по мере масштабирования служб, новые файлы должны подхватываться автоматически. В каталогах присутствуют сжатые архивы и нумерованные ротированные файлы (app.log.1, app.log.2.gz), которые собирать не нужно.

Поле Путь:

/var/log/apps/**/*.log

Дополнительные параметры:

{
"fileWatcher": {
"scanner": {
"recursiveGlob": true,
"includeFiles": ["\\.log$"],
"excludeFiles": ["\\.gz$", "\\.\\d+$"]
}
}
}

recursiveGlob: true раскрывает ** на глубину до 8 уровней. includeFiles оставляет только активные .log-файлы, excludeFiles отбрасывает архивы (*.gz) и нумерованные ротированные файлы (*.1, *.2, …).

Сценарий 3. Журналы nginx с ротацией logrotate

nginx ротирует журналы доступа через logrotate: активный файл переименовывается в access.log.1, создаётся новый пустой access.log, старые архивы пакуются в gzip. Коллектор должен закрыть обработчик переименованного файла, открыть новый и не читать архивные копии повторно.

Поле Путь:

/var/log/nginx/access.log
/var/log/nginx/error.log

Дополнительные параметры:

{
"close": {
"onStateChange": {
"renamed": true,
"removed": true,
"inactive": "30s"
}
},
"fileWatcher": {
"scanner": {
"excludeFiles": ["\\.\\d+$", "\\.gz$"]
}
}
}

renamed: true закрывает обработчик при переименовании активного файла во время ротации. inactive: "30s" освобождает дескриптор файла, в который не пишут более 30 секунд — это уменьшает количество открытых файлов при большом числе виртуальных хостов.

Сценарий 4. Многострочные stack trace Java-приложения

Журнал Java-приложения содержит многострочные стек трейсы. Каждая запись начинается со строки с меткой времени вида 2026-05-27 10:30:15, последующие строки трейса начинаются с пробельных символов и относятся к той же записи.

Поле Путь:

/opt/myapp/logs/application.log

Дополнительные параметры:

{
"reader": {
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_MULTILINE",
"multiline": {
"type": "MULTILINE_TYPE_PATTERN_MODE",
"pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
"negate": true,
"match": "after",
"timeout": "5s",
"maxLines": 500
}
}
]
}
}
}

Регулярное выражение распознаёт строки, начинающиеся с метки времени. negate: true инвертирует проверку: строки, не соответствующие шаблону (продолжения трейса), присоединяются к предыдущему событию по правилу match: after. timeout: "5s" гарантирует отправку события, если новые строки не поступают, maxLines: 500 ограничивает размер одного события во избежание неконтролируемого роста при некорректных журналах.

Сценарий 5. Журналы Windows-сервиса по SFTP в кодировке Windows-1251

Сбор журналов прикладного сервиса с удалённого узла Windows через SFTP. Файлы сохранены в кодировке Windows-1251 (кириллица) и используют разделитель строк CRLF (\r\n). Имена файлов содержат дату и обновляются ежедневно.

Параметры подключения: протокол SFTP, IP-адрес узла Windows, учётная запись с правом чтения каталога журналов.

Поле Путь:

C:/ProgramData/MyService/logs/*.log

Дополнительные параметры:

{
"reader": {
"encoding": "ENCODING_WINDOWS1251",
"lineTerminator": "LINE_TERMINATOR_CARRIAGE_RETURN_LINE_FEED"
},
"close": {
"onStateChange": {
"inactive": "5m"
}
}
}

ENCODING_WINDOWS1251 корректно декодирует кириллические символы; без этого параметра коллектор по умолчанию интерпретирует ввод как UTF-8 и кириллица отображается заменителями. inactive: "5m" повышает порог простоя — журналы по SFTP обновляются реже, чем локальные файлы, и преждевременное закрытие дескриптора приводит к лишним SFTP-сессиям.

Сценарий 6. JSON-журналы контейнеров Docker

Docker записывает журналы каждого контейнера в отдельный JSON-файл в каталоге /var/lib/docker/containers/<container-id>/<container-id>-json.log. Каждая строка файла — это JSON-документ вида {"log": "...", "stream": "stdout", "time": "..."}. Коллектор должен извлечь поле log в качестве текста события и метку времени time вместо времени чтения строки. Для каждого нового контейнера появляется новый подкаталог, который должен подхватываться автоматически.

Поле Путь:

/var/lib/docker/containers/*/*-json.log

Дополнительные параметры:

{
"reader": {
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_CONTAINER"
}
]
}
}
}

Парсер PARSER_KIND_CONTAINER автоматически распознаёт формат (docker, json_file, cri) и принимает оба потока — stdout и stderr. Дополнительная настройка из UI не требуется: формат и поток выбираются автоматически.

предупреждение

Каталог /var/lib/docker/containers/ по умолчанию доступен только пользователю root или членам группы docker. Учётная запись, от имени которой запущена служба komrad-file-collector, должна быть включена в группу docker либо иметь явные права на чтение этого каталога.

При использовании платформы Kubernetes (containerd, CRI-O) подходит тот же сценарий с путём /var/log/pods/**/*.log — парсер распознает CRI-формат автоматически.

Удаление

Файловый коллектор удаляется командой:

sudo dpkg -P komrad-file-collector