Агент ETL

  8 минутное чтение  

Агент получения и записи данных реализует сервис по сбору данных из множества различных СУБД и записи их в целевые базы. Управление сервисом осуществляется посредством передачи HTTP-команд на создание/остановку задач. Мониторинг сервиса осуществляется посредством встроенного web-сервиса. Сервис может логировать свои действия как в локальный файл, так и на удаленный сервис логирования.
Для просмотра запущенных заданий также доступна web страница по адресу http://имя-сервера-с-агентом:порт-агента

Поддерживаемые базы данных:

Установка Агента ETL

Агент устанавливается в систему Windows или Linux как системный сервис.

Как узнать версию агента:

  1. Запустить исполняемый файл с ключом -version
  2. Посмотреть на главной странице сервиса в браузере
  3. Получить в заголовке ответа по пути /check
  4. Посмотреть в файле логов

Для Windows

Для установки в систему Windows необходимо запустить от имени администратора файл setupagentetl.exe, расположенный в поставке с обновлением Modus ETL, выбрать папку установки и нажать “Установить”.

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

После установки создается служба, которая логирует свои действия в системный журнал.
Возможна установка новой версии Агента ETL поверх запущенной (служба принудительно останавливается перед обновлением).

После установки автоматически создается служба “AgentETL”.

Для Linux систем

Для установки в систему linux предусмотрена возможность регистрации сервиса в systemd (Debian 8+, Ubuntu 16.04+, CentOS 7+). Для этого необходимо выполнить установку пакета для соответствующей системы (deb или rpm):

Для deb-пакета (Ubuntu, Debian) команда:

sudo apt-get install unixodbc && sudo dpkg -i agentetl_*_amd64.deb

Для rpm-пакета (CentOS) команда:

	sudo yum install unixODBC && sudo rpm -i agentetl-*-1.x86_64.rpm

При этом, в каталог /opt/agentetl будет скопирован файл программы и создан файл настроек /etc/agentetl/settings.json, который можно отредактировать интерактивно, выполнив в консоли команду:

	sudo agentetlcfg

Также будет создан файл демона для systemd и запущен сам демон.

По соображениям безопасности, желательно запускать службу от отдельного пользователя. Для этого его нужно создать и внести соответствующие изменения в файл настройки /etc/systemd/system/agentetl.service.

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

	sudo systemctl restart agentetl

Удалить deb-пакет (Ubuntu, Debian) можно командой:

	sudo dpkg -r agentetl

Удалить rpm-пакет (CentOS) можно командой:

	sudo rpm -e agentetl

Просмотреть статус активности сервиса и последние строки его лог-файла можно командой:

	sudo systemctl status agentetl

Файл логов будет размещен в /var/log/agentetl/

Настройка параметров Агент ETL

Настройка параметров агента может быть выполнена: при установке и обновлении приложения в консоли или редактируя файл settings.json

Файл представляет из себя json-файл:

	{
		"Addr": ":8000",
		"TLSCertFile": "",
		"TLSKeyfile": "",
		"Login": "user",
		"Password": "123",
		"LogFile": "",
		"SaveStatsToFile": "",
		"Servers": [],
		"ETLLogURL": "",
		"ETLLogInterval": 30,
		"ETLSuccessURL": "",
		"Capacity": 200000,
		"Workers": 50,
		"Bulksize": 50000,		
    	"Databases": {
        	"Vertica" : {
            	"InMemoryResultRowLimit": 200000,
				"CopyBlockSizeBytes": 65536
        	}
		}
    }

Параметры:

  • Addr - ip-адрес и порт, в формате адрес:порт(слушается интерфейс адрес) или :порт(слушаются все сетевые интерфейсы), которые будет использовать Агент ETL
  • TLSCertFile - путь к файлу сертификата TLS (*.pem) (если пустой, то TLS не будет использоваться)
  • TLSKeyfile - путь к файлу ключа TLS (*.key)
  • Login - логин для basicauth доступа к API сервиса
  • Password - пароль для basicauth доступа к API сервиса
  • LogFile - путь к файлу для записи детального лога
  • SaveStatsToFile - путь к файлу для записи статистических данных (*.xml)
  • Servers - адреса (и порты) других агентов (для режима балансировщика)
  • ETLLogURL - URL для отправки лога событий ETL в формате:
    http://ИмяПользователя:Пароль@СерверСПубликацией/ИмяБазы/hs/AgentsUpload/Logs
  • ETLLogInterval - периодичность отправки лога событий ETL, секунд
  • ETLSuccessURL - URL для отправки в ETL события успешного завершения задачи в формате:
    http://ИмяПользователя:Пароль@СерверСПубликацией/ИмяБазы/hs/AgentsUpload/ack
  • Capacity - макс. количество параллельно обрабатываемых строк
  • Workers - количество параллельных воркеров
  • Bulksize - размер “пачки” для вставки при сборе данных (по-умолчанию 20000 строк)
  • Databases - настройки драйверов для соответствующих СУБД
    • Vertica - настройки для работы с СУБД Vertica
      • InMemoryResultRowLimit - количество строк, которые будут загружены в память при чтении из СУБД Vertica. Остальные данные записываются в файловый кэш.
      • CopyBlockSizeBytes - размер пакета в байтах, которым отправляются данные для записи в СУБД Vertica

С помощью настроек Capacity и Workers возможно управлять параметрами процесса, для обеспечения адаптивности под разные конфигурации аппаратного обеспечения.
Capacity - регулирует размер буфера, выделяемый в памяти для хранения указанного количества прочитанных строк.
Workers - регулирует количество “процессов-воркеров”, выполняемых одновременно и передающих считанные строки в базы данных хранилища.
Одни воркер обрабатывает задачу записи для одного источника. Чтение и запись при этом выполняются параллельно.
С помощью настроек TLS-сертификата сервиса поддерживается шифрование https-соединений с сервисом.
Сервис требует basic-аутентификацию подключающегося пользователя. Логин и пароль к нему указываются в соответствующих свойствах файла settings.json.

После изменения параметров службу Агента необходимо перезапускать

Резервное копирование

Для восстановления работоспособности Агента после каких-то сбоев достаточно иметь дистрибутив АгентаETL и файл с настройками settings.json. Поэтому для резервирования достаточно выполнять архивацию файла settings.json.

В системе linux файл по умолчанию находится в каталоге /etc/agentetl/.
В системе windows находится в папке, куда был установлен АгентETL.

Для восстановления достаточно выполнить следующие действия:

  1. Установить Агент ETL из дистрибутива.
  2. Восстановить файл с настройками settings.json по нужному пути(linux - /etc/agentetl/, windows - в папку с установленным Агентом)
  3. Перезапустить службу агента.

Логирование

Агент логирует свои действия в стандартный поток ошибок консоли. Этот поток сохраняется в системных журналах windows и linux.
Дополнительно агент может логировать свои действия в отдельный текстовый файл, для последующего анализа проблем с производительностью и/или работой агента. Имя файла для сохранения лога указывается в настройке LogFile (см. Настройка агента).
Агент может взаимодействовать с внешним http-сервисом для ведения лога в ETL, если в настройке ETLLogURL указан полный путь к сервису логирования ETL, включая данные об аутентификации.
Формат ETLLogURL: http(s)://user:pass@host:port/path.

Получение и запись данных Агентом под управлением ETL

Общий алгоритм сбора данных Агентом

  1. ETL передает настройки источника, приемника, текст запроса, параметры и т.д. Агенту.
  2. Агент запускает процесс по получению данных
  3. Агент отправляет информацию в ETL по основным этапам получения данных: время начала/окончания, количество строк, возникшие ошибки и т.п.
  4. ETL периодически опрашивает Агент о состоянии выполняемых задач.
  5. По завершению перекачки данных Агент сообщает в ETL об этом.

Возможные этапы при сборе данных

  1. COMСоединение – общий этап выполнения задачи по «перекачке». Он должен быть самым первым и самым последним. При передачи этого этапа в качестве успешного завершения работы обязательно передается Количество строк записанных в приемник.

  2. ПолучениеДанныхИсточника – этап начинается с момента подключения к источнику и началу выполнения запроса. Завершается моментом окончания чтения данных из источника.

  3. ЗаписьДанныхВоВнешнееХранилище – этап начинается в момент начала записи данных в приемник и завершается по окончанию. При описании окончания этого этапа передается количество строк, записанных в приемник.

Важные особенности записи данных

Одно задание на перекачку данных является атомарным.
В рамках одного задания может быть выполнено несколько одинаковых запросов на чтение данных с разными параметрами. Однако, все считанные данные далее будут составлять одну транзакцию записи.
Агент учитывает, что в таблицу приемник могут писать и другие Задания, поэтому таблица может быть не пустой, а добавление данных должно производится методом добавления, без очистки целевой таблицы.
Для обеспечения атомарности, для каждого типа целевых баз данных используются следующие методы записи:

  1. MS SQL
  • Формируется запрос для массовой вставки INSERTBULK в целевую таблицу с признаком необходимости установки блокировки Tablock
  • Данные потоком отправляются на сервер СУБД.
  • После завершения чтения и записи всех данных выполняется фиксация общей транзакции.
  • Сервер MS SQL должен находиться в одном часовом поясе с агентом. В противном случае, для колонок с датами любых типов, кроме DATETIMEOFFSET, возможно неверное определение часового пояса.
  • Колонки с типом DATETIMEOFFSET не подвержены проблемам с часовыми поясами, т.к. содержат (и агент транслирует без потерь) информацию о них вне зависимости от часовых поясов сервера и агента. Рекомендуется использовать колонки такого типа для целевых таблиц.
  1. Postgresql
  • Формируется запрос для массовой вставки COPY в целевую таблицу.
  • Данные потоком отправляются на сервер СУБД.
  • После завершения чтения и записи всех данных выполняется фиксация общей транзакции.
  • Работа с часовыми поясами дат происходит без потери информации о часовом поясе.
  1. Oracle / ODBC
  • В Oracle или ODBC-базе данных все данные вставляются одной транзакцией, без использования временных таблиц.
  • В настройках такой базы достаточно указать Type = “oracle” или “odbc” и полную строку соединения в параметре Database, остальные параметры (Address, Login, Password) не используются.
  • Для linux используется пакет unixODBC, который должен быть установлен отдельно, так же как и необходимый ODBC драйвер(в том числе и Oracle).
  • Для Windows достаточно установить и настроить только ODBC драйвер(в том числе и Oracle).
  1. Vertica
  • Формируется запрос для массовой вставки COPY в целевую таблицу.
  • Данные потоком отправляются на сервер СУБД.
  • Данные вставляются несколькими запросами COPY. Количество строк в одном запросе устанавливается в параметре Bulksize файла Settings.json
  • После завершения чтения и записи всех данных выполняется фиксация общей транзакции.
  • Управлять процессом массовой вставки можно используя переменные среды:
    VERTICA_ABORT_COPY_ON_ERROR - 0/1. Если установлено значение 0, тогда данные будут вставлены даже в случае ошибок разбора входных данных на стороне СУБД Vertica. Для других значений параметра(в том числе и если параметр отсутствует) будет выполнятся прерывание массовой вставки с записью причины в лог-файл.
    VERTICA_COPY_AUTO_COMMIT - 0/1. Если установлено значение отличное от 1(либо вообще не установлено), тогда к запросу будет добавлен параметр NO COMMIT. Данный параметр означает, что после выполнения запроса вставки COPY не будет автоматом выполнена фиксации транзакции(COMMIT выполняется один раз после вставки всех данных).
    VERTICA_TABLE_WITH_REJECTED_DATA - имя таблицы для вставки “отбракованных” данных.
    Если используется режим NO COMMIT, то при отсутствии таблицы из VERTICA_TABLE_WITH_REJECTED_DATA она будет создана как LOCAL TEMP.
  1. ClickHouse
  • Вставка в таблицу приемник происходит посредством промежуточной таблицы. Вначале данные накапливаются в промежуточной таблице, затем копируются из промежуточной в целевую (приемник).
  • Промежуточная таблица может быть как временной (Temporary), так и обычной. Зависит это от версии СУБД. Начиная с версии 23.3.0.0 используется временная (Temporary) таблица.
  • Промежуточная таблица создается с движком MergeTree.
  • Промежуточная таблица (обычная) удаляется после завершения задачи или в случае ошибки. Возможна ситуация при которой, в результате критических сбоев, промежуточная таблица удалена не будет. Для исключения подобных ситуаций желательно на версиях СУБД ниже 23.3.0.0 периодически запускать скрипт удаления промежуточных таблиц.
  • Промежуточная таблица получает наименование на основании шаблона имени и отметки времени в наносекундах.
    Шаблон: “etl_tmp_$timestamp_nano”.
    Пример: “etl_tmp_1683294532542734300”.