Tail

Общие сведения

Название плагина: tail

Описание:

Плагин предназначен для чтения лог-файлов.

⚠️ Может быть использован только при настройке Рабочей конфигурации агента.

Формат сценария рабочей конфигурации агента

continuous-jobs:
  - init-step:
      plugin: tail
      with:
        bufferType: memory
        bufferSize: 32768
        chunkSize: 32768
        paths:
          - /opt/program-1/*.log
          - /opt/program-2/*.log
        dataBase: PluginTail.db
        readFromHead: false
        multilineParser:
          - java
          - python
          - go
        refresh: 1000
        streamKey: "ключ потока"

Параметры конфигурации используемые в сценарии

Параметр	Тип	Обязательный параметр	Значение по умолчанию	Возможные значения	Описание
bufferType	string	нет	memory	memory/filesystem	Определяет тип памяти для очереди
bufferInputName	string	нет	{название плагина}.{идентификатор задания}	Любая строка	Параметр необходим, если пользователь хочет читать разные файлы с использованием нескольких job в одной рабочей конфигурации или использовать несколько рабочих конфигураций для чтения файлов. Определяет название папок для хранения "порций", если указан filesystem и дает плагину возможность идентифицировать буфер, если используется memory.
bufferSize	string	нет	= chunkSize	Любое число	Определяет максимальный размер буфера в килобайтах для приема сообщения. Если не задано, по умолчанию будет использовано значение chunkSize.
chunkSize	string	нет	32768	Любое число	Задает максимальный размер "порций" данных для хранения входящих сообщений
paths	string (array)	да	-	Любая строка	Используется для указания пути к файлам, которые необходимо отслеживать
readFromHead	string	нет	true	Любая строка	Параметр определяет откуда плагин будет читать файл. Если true - плагин будет читать файл с самого начала, если false - с последнего места остановки предыдущего чтения
dataBase	string	нет	<monq-agent>\DB\Tail.db	Любая строка	В данном параметре необходимо указать путь к файлу БД, где будет создан файл базы данных SQLLite, чтобы отслеживать какая часть файла уже прочитана и откуда нужно начинать чтение в следующий раз
refresh	number	нет	-	Любое положительное значение в миллисекундах	Параметр отвечает за обновление файлов в директории. Если пользователь в paths указал чтение всех файлов в папке, то плагин будет проверять наличие новых файлов в папке с частотой указанной в данном параметре
multilineParser	string (array)	нет	-	Любая строка	Определяет какой парсер использовать для разбора мультистрок. Можно указать сразу несколько парсеров, при разборе строк плагин будет пытаться распарсить строки любым из указанных парсеров
streamKey	string	да	-	Любая строка	Ключ потока, в который необходимо отправлять собранные данные

Параметр paths

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

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

Также можно указать несколько шаблонов, что делает этот параметр очень гибким для настройки отслеживания файлов в различных конфигурациях системы.

Примеры:

• Чтение одного файла: C:\Logs\application.log

  Если файл не найден или директория указана не верно, агент сообщит об ошибке.

• Чтение нескольких файлов:

  Пользователь может указать несколько файлов используя параметр paths как массив:

  paths:
    - C:\Logs\application.log
    - C:\Logs\system.log

• Чтение всех файлов в директории с определенным расширением: C:\Logs\*.log.

  Если директория указана не верно, агент сообщит об ошибке.

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

Параметр readFromHead

Этот параметр определяет с какой позиции файла плагин будет читать его читать.

Если значение false плагин начинает читать файлы с текущего места игнорируя существующие записи.

Если значение true плагин переходит к файлу с БД (путь к файлу указывается в параметре dataBase). Если файл найден и плагин находит запись в БД для файла который собирается читать, плагин начинает чтение файла с того места, где остановился в прошлый раз и сделал запись в БД. Если файл БД не найден или не найдена запись для конкретного файла, который собирается читать плагин, такой файл будет читаться с самого начала.

Также возможны следующие ситуации:

• Плагин хранит в БД, что для файла прочитал 500 байт, однако в файле были изменения (пока агент не работал) и теперь там всего информации на 300 байт. В таком случае плагин начнет чтение данного файла с самого начала, если readFromHead=true.
• Плагин хранит в БД, что для файла прочитал 500 байт, однако в файле произошли изменения (пока агент не работал) и теперь в файле 600 байт данных, но все они новые и плагин на самом деле их вообще не читал. Допустимо, что плагин все равно начнет чтение данного файла проигнорируя первые 500 байт информации т.к он не сможет отличить старые данные от новых.

Параметр refresh

Если пользователь указал чтение всех файлов в директории с определенным расширением: C:\Logs\*.log и на момент запуска плагина в директории было 2 файла с таким расширением, агент начнет их читать.

Если параметр задан и в папке появится еще один файл с разрешением *.log, то после срабатывания refresh новый файл так же начнет читаться.

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

Параметр multilineParser

Для разбора логов, содержащих мультистроки можно указать используемые парсеры для этого.

На текущий момент плагин имеет встроенные парсеры, которые работают со следующим списком форматов парсинга мультистроковых лог файлов:

• go
• python
• java

Параметр dataBase

При настройке задания пользователь может указать директорию в которой будет создан файл БД для хранения "отметок" для файлов которые плагин уже прочитал.

Если при запуске плагина файл по данному пути отсутствует плагин создает автоматически файл БД с простой таблицей, благодаря которой плагин будет знать на каком месте он закончил чтение каждого файла в случае аварии или остановки работы.

При перезапуске агента, плагин продолжит чтение файла с того места где остановился в прошлый раз, если в параметре readFromHead стоит true.

Если параметр dataBase отсутствует - автоматически создается файл и папка по пути "папка где установлен агент"\DB\Tail.db

Ротация логов

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

• Перемещение
• Переименование
• Удаление

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