Агент ETL

Агент ETL — это дополнительный модуль для многопоточной обработки данных: выполняет сбор и запись данных из различных СУБД и записывает их в целевые базы.

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

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

MS SQL;
Postgres SQL;
Vertica;
Oracle DB;
ClickHouse;
Greenplum Database;
Информационные базы 1С (только получение).

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

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

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

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

Для Windows

Для установки в систему Windows необходимо:

Запустить от имени администратора файл «setupagentetl.exe», выбрать папку установки и нажать «Установить».
Далее запустится консоль установки начальных параметров агента. Если не вводить значения параметров, они установятся по умолчанию (нажать клавишу «Enter» без ввода значений). Изменить их можно в файле «settings.json», расположенном в каталоге, куда был установлен Агент ETL.
Проверить работоспособность агента можно в браузере по адресу «http://имя-сервера-с-агентом:порт-агента».

Возможна установка новой версии Агента 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».

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

Шифрование файла settings.json

Для шифрования определенных значений в конфигурационных файлах используется специальная утилита encryption-settings.

Шифрование рекомендуется применять к файлам, которые содержат настройки, доступные для ручного редактирования, например, к файлу settings.json — конфигурационному файлу Агента ETL

Для определения необходимых полей файла конфигурации создайте файл с расширением *.jsonpath и укажите поля для шифрования:
```
{
  "secrets": [
    "$.Password",
    "$.ETLLogURL",
    "$.ETLSuccessURL"
  ]
}
```
Генерация ключей.
Запустите утилиту с параметром для генерации ключей, выполнив команду:
```
<утилита> -g
```
После выполнения ключи создаются в текущем каталоге:
- public_key.pem — публичный ключ;
- private_key.pem — приватный ключ.
Шифрование настроек
После того, как ключи сгенерированы, можно перейти к процессу шифрования конфигурационных файлов. Для этого выполните команду:
```
<утилита> -e -settings <путь к файлу конфигурации> -key <путь к файлу с публичным ключом> -fields <путь к файлу со списком полей для шифрования>
```
При этом:
- <путь к файлу конфигурации> – укажите путь к файлу, который нужно зашифровать (например, settings.json);
- <путь к файлу с публичным ключом> – укажите путь к файлу с публичным ключом, который был сгенерирован;
- <путь к файлу со списком полей для шифрования> – укажите путь к вашему файлу *.jsonpath.
После шифрования указанные поля будут иметь вид:
```
  "metadata": {
    "datasource": {
      "encrypted": true,
      "value": "XUN8ygFGdRl4FtWiVDhD+ZELfPkHY+EjpDkWEDtjItzTOdGqpCFP36irQiHCDPy2a/a4MdzN9yTlDBBRntRmQG3Pg6P3y5wJMGarQC9pfu8LALp8x+HQgh5ggAffZZNKfRofoqYES9YnFuiB9kPk31BkMAAU4WLNV+NZYpFx8ZYbuaYF0AAOvf/FYOHzr/Qh4109xITCEAODS5ph0cRWQRoQI/jScGn/TrM6XfzjTw+joC38uKG/zQMwAfZBQ/qSz8Aa5ybEIlNcSOuKf6AdoivaTtPepkweF2F/8csgXdAjC1iNySsDMeOyKg7OlackN0kXQGDKXW/3VNA8iKf7ufSBB/eD"
    }
```

После выполнения в файле конфигурации зашифровываются указанные поля.

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

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

Для восстановления работоспособности Агента после каких-то сбоев достаточно иметь дистрибутив Агента 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».
После завершения чтения и записи всех данных выполняется фиксация общей транзакции.
Управлять процессом массовой вставки можно используя переменные среды:
1. VERTICA_ABORT_COPY_ON_ERROR — 0/1. Если установлено значение 0, тогда данные будут вставлены даже в случае ошибок разбора входных данных на стороне СУБД Vertica. Для других значений параметра (в том числе и если параметр отсутствует) будет выполнятся прерывание массовой вставки с записью причины в лог-файл.
2. VERTICA_COPY_AUTO_COMMIT — 0/1. Если установлено значение отличное от 1 (либо вообще не установлено), тогда к запросу будет добавлен параметр NO COMMIT. Данный параметр означает, что после выполнения запроса вставки COPY не будет автоматом выполнена фиксации транзакции (COMMIT выполняется один раз после вставки всех данных).
3. 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».

Установка Агента ETL - Продукт Modus BI