Агент ETL
8 минутное чтение
Агент получения и записи данных реализует сервис по сбору данных из множества различных СУБД и записи их в целевые базы. Управление сервисом осуществляется посредством передачи HTTP-команд на создание/остановку задач. Мониторинг сервиса осуществляется посредством встроенного web-сервиса. Сервис может логировать свои действия как в локальный файл, так и на удаленный сервис логирования.
Для просмотра запущенных заданий также доступна web страница по адресу «http://имя-сервера-с-агентом:порт-агента».
Поддерживаемые базы данных:
- MS SQL;
- Postgres SQL;
- Vertica;
- Oracle DB;
- ClickHouse;
- Greenplum Database;
- Информационные базы 1С (только получение).
Установка Агента 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».