Агент ETL

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

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

Для просмотра запущенных заданий также доступна web страница по адресу «http://имя-сервера-с-агентом:порт-агента».

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

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

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

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

запустить исполняемый файл с ключом -version;

посмотреть на главной странице сервиса в браузере;

получить в заголовке ответа по пути «/check»;

проверить в файле логов.

Для 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»;
установить в качестве владельца нового пользователя для папок и всех вложенных файлов:
- «/opt/agentetl»;
- «/etc/agentetl»;
- «/var/log/agentetl».

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

	sudo systemctl daemon-reload 
	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 — размер «пачки» для вставки при сборе данных (по умолчанию 20 000 строк);
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.

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

Установить Агент ETL из дистрибутива.
Восстановить файл с настройками «settings.json» по нужному пути (Linux — «/etc/agentetl/», Windows — в папку с установленным Агентом).
Перезапустить службу Агента.

Логирование

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

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

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

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

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

«COMСоединение» — общий этап выполнения задачи по «перекачке». Он должен быть самым первым и самым последним. При передачи этого этапа в качестве успешного завершения работы обязательно передается количество строк записанных в приемник.
«ПолучениеДанныхИсточника» — этап начинается с момента подключения к источнику и началу выполнения запроса. Завершается моментом окончания чтения данных из источника.
«ЗаписьДанныхВоВнешнееХранилище» — этап начинается в момент начала записи данных в приемник и завершается по окончанию. При описании окончания этого этапа передается количество строк, записанных в приемник.

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

Одно задание на перекачку данных является атомарным.

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

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

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

MS SQL:

формируется запрос для массовой вставки INSERTBULK в целевую таблицу с признаком необходимости установки блокировки Tablock;
данные потоком отправляются на сервер СУБД;
после завершения чтения и записи всех данных выполняется фиксация общей транзакции;
сервер MS SQL должен находиться в одном часовом поясе с агентом. В противном случае, для колонок с датами любых типов, кроме DATETIMEOFFSET, возможно неверное определение часового пояса;
колонки с типом DATETIMEOFFSET не подвержены проблемам с часовыми поясами, т.к. содержат (и агент транслирует без потерь) информацию о них вне зависимости от часовых поясов сервера и агента; Рекомендуется использовать колонки такого типа для целевых таблиц.

Postgresql:

формируется запрос для массовой вставки COPY в целевую таблицу;
данные потоком отправляются на сервер СУБД;
после завершения чтения и записи всех данных выполняется фиксация общей транзакции;
работа с часовыми поясами дат происходит без потери информации о часовом поясе.

Oracle / ODBC:

в Oracle или ODBC-базе данных все данные вставляются одной транзакцией, без использования временных таблиц;
В настройках такой базы достаточно указать Type = "oracle" или "odbc" и полную строку соединения в параметре Database, остальные параметры (Address, Login, Password) не используются;
для Linux используется пакет «unixODBC», который должен быть установлен отдельно, так же как и необходимый ODBC-драйвер (в том числе и Oracle).
для Windows достаточно установить и настроить только ODBC драйвер (в том числе и Oracle).

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.

ClickHouse:

вставка в таблицу приемник происходит посредством промежуточной таблицы. Вначале данные накапливаются в промежуточной таблице, затем копируются из промежуточной в целевую (приемник);
промежуточная таблица может быть как временной (Temporary), так и обычной. Зависит это от версии СУБД. Начиная с версии 23.3.0.0 используется временная (Temporary) таблица;
промежуточная таблица создается с движком «MergeTree»;
промежуточная таблица (обычная) удаляется после завершения задачи или в случае ошибки. Возможна ситуация при которой, в результате критических сбоев, промежуточная таблица удалена не будет. Для исключения подобных ситуаций желательно на версиях СУБД ниже 23.3.0.0 периодически запускать скрипт удаления промежуточных таблиц;
промежуточная таблица получает наименование на основании шаблона имени и отметки времени в наносекундах.

Шаблон: «etl_tmp_$timestamp_nano».

Пример: «etl_tmp_1683294532542734300».