Child pages
  • Механизм выгрузки объектов из внешних источников ETL
Skip to end of metadata
Go to start of metadata

ETL

В мире многообразия систем, выполняющих различные задачи, часто возникает задача на основании данных одной или нескольких систем создать объекты (таблицы или сущности) в другой системе. В общем случае за это отвечает механизм ETL.

ETL (от англ. ExtractTransformLoad — дословно «извлечение, преобразование, загрузка»). Это системы корпоративного класса, которые применяются, чтобы привести к одним справочникам и загрузить одну систему данные из нескольких разных учетных систем. Т.е. решает задачу однонаправленного обмена данными между исходной и целевой системой.

Подробнее можно почитать:


NOC ETL

В NOCе реализован базовый функционал ETL - возможность извлекать данные из внешней системы (Remote System) и на них основе получать объеты в НОКе. На данный момент возможна вгрузка следующих сущностей:

  • Зоны ответсвенности (Administrative Domain)
  • Объекты управления (Managed Object)
  • Профили объектов (Manged Object Profile)
  • Сегменты (Segments)
  • Точки присутствия (PoP)
  • Профили аутентификации (Auth profile)
  • Сервисы (Services)
  • Абоненты (Subscribers)
  • Линки (Links)
  • Ресурсные группы (Resource Group)

Кратко механизм выглядит так:

  1. Реализуется адаптера выгрузки (extractor). Его задача - получить данные из внешней системы и отдать в виде списка полей, определённых в загрузчике. Подробнее см главу Загрузка
  2. В интерфейсе настраивается Внешняя система и выбираются реализованные загрузчики
  3. После настройки даётся команда ./noc etl extract <remote_system_name>. Происходит извлечение информации из внешней системе (при помощи адаптера, написанного на шаге 1). Всё складывается в файлы import.csv.gz в директории /var/lib/noc/import/<remote_system_name>/<loader_name>/import.csv.gz
  4. Командой ./noc etl check <remote_system_name> проверяем целостность выгрузки
  5. Командой ./noc etl diff <remote_system_name> смотрим изменения относительно предыдущего файла выгрузки. В первым раз все объекты будут показаны как новые.
  6. Командой ./noc etl load <remote_system_name> заливаем данные в НОК (при этом создаются объекты соотв. загрузчику).

После окончания файл import.csv.gz перемещается в папку /var/lib/noc/import/<remote_system_name>/<loader_name>/archive/import_date.csv.gz и файл mappings.csv дополняется связкой: ID внешней системы <-> ID НОКа

Путь /var/lib/noc/import задаётся настройкой path -> etl_import

Настройка внешней системы

Настройка начинается в пункте меню Main -> Setup -> Remote Systems. После нажатия на кнопку Add открывается форма создания внешней ситемы с пунктами:

  • Name - имя внешней системы. Будет использоваться при работе с командой ETL. Желательно выбирать краткое и без пробелов.
  • Description - описание (какой-нибудь текст)
  • Handler - ссылка на адаптер загрузки в виде строчки импорта питона.

Н-р: noc.custom.etl.extractors.zabbix.ZBRemoteSystem рассчитывает, что файлик лежит в кастоме по пути <custom_folder>/etl/extractor/zabbix.py

  • Extractors/Loaders - список доступных для моделей для загрузки. Требует реализацию в адаптере.
  • Environment - настройки адаптера загрузки (передаются в него при работе)

Также, в объектах, поддерживающих создание из механизма ETL присутствуют поля:

  • Remote System - это указание из какой внешней системы приехал объект
  • Remote ID - текстовое поле, ID объекта во внешней системе

Поля Remote SystemRemote ID заполняются автоматически. Вносить изменения вручную не рекомендуется.

После настройки внешней системы дальнейшая работа идёт с командой ./noc etl. Для лучшего понимания мы начнём рассмотрение с последнего этапа - загрузки в НОК.

Загрузка

Загрузка заливка извлечённых данных в НОК выполняется командой ./noc etl load REMOTE_SYSTEM_NAME <loadername>. Происходит применение изменений по следующем правилам:

  • При создании объекта связка ID внешней системыID Объекта в NOCе записывается в файл mappings.csv, расположенным в папке загрузчика.
  • при создании PoP (Point of Presence)по пути создаются объекты типа контейнер
  • изменения считаются относительно данных предыдущей загрузки (!не данных в НОКе)
  • удалённые объекты управления (Managed Object) переводятся в состояние unmanaged
  • при удалении сегмента с находящиеся в нём объекты перемещаются в сегмент ALL

Важно понимать, что изменения вычисляются относительно предыдущей загрузки (предыдущего состояния) из внешней системы. По этой причине, если внести изменения по полю в НОКе - загрузка эти изменения не откатит.
Также, если потерять архивные файлы по последней выгузке, то все объекты будут пересозданы.

Адаптеры для загрузки (загрузчики), ответственные за создание расположены в директории core/etl/loader. Разберём на примере managedobject(core/etl/loader/managedobject.py):

ManagedObject Loader
class ManagedObjectLoader(BaseLoader):
    """
    Managed Object loader
    """
    name = "managedobject"  # Имя (Loader Name)
    model = ManagedObject   # NOC object Model (модель, создаваемая адаптером)
    fields = [        # Список полей, необходимых для создания
                     # объекта
        "id",            
        "name",
        "is_managed",
        "container",
        "administrative_domain",
        "pool",
        "segment",
        "profile",
        "object_profile",
        "static_client_groups",
        "static_service_groups",
        "scheme",
        "address",
        "port",
        "user",
        "password",
        "super_password",
        "snmp_ro",
        "description",
        "auth_profile",
        "tags",
        "tt_system",
        "tt_queue",
        "tt_system_id"
    ]

    mapped_fields = {  # карта связей полей с другими вгрузчиками (loader)
        "administrative_domain": "administrativedomain",
        "object_profile": "managedobjectprofile",
        "segment": "networksegment",
        "container": "container",
        "auth_profile": "authprofile",
        "tt_system": "ttsystem",
        "static_client_groups": "resourcegroup",
        "static_service_groups": "resourcegroup"
    }


Структура загрузчика состоит из аттрибутов:

  • Атрибут name. По нему происходит сопоставление загрузчика и файла выгрузки с данными.
  • model - Указания на модель, загрузку которой он реализует
  • fields - списка полей, которые должны присутствовать в файле выгрузки.
  • mapped_fields - связаные поля. Заполняется когда поле является указателем на запись извлекаемую другим загрузчиком

Остановимся на карте связей подробнее. Для системы нормально, когда одни сущности связываются с другими. Это позволяет не мешать всё в одну кучу, по этой причине и существуют карты связей (mappings map). В примере указано что поле object_profile необходидо связать с вгрузчиком managedobjectprofile. Сама привязка идёт по полям ID (всегда первые в списке), а сам вгрузчик ищется по имени:


Рассмотрим пример загрузчика для ManagedObject Profile

ManagedObjectProfile Loader
class ManagedObjectProfileLoader(BaseLoader):
    """
    Managed Object Profile loader
    """
    name = "managedobjectprofile"
    model = ManagedObjectProfile
    fields = [
        "id",
        "name",
        "level"
    ]

Как видно, для managedobjectprofile достаточно 3 полей: idимяуровень. При этом, карта связей (mapped_fields) отсутствует.

При работе с картами связей, необходимо помнить - что не все поля являются обязательными. Н-р для модели managedobject обязательными являются: administrative_domainobject_profilesegment

следовательно, для реализаци адаптера выгрузки объектов управления (ManagedObject), необходимо будет реализовать выгрузку для administrativedomainnetworksegment и managedobjectprofile. Иначе при выполнении команды ./noc etl check будет множество ошибок вида:

[noc.core.etl.loader.base] [RS|managedobject] ERROR: Field #4(administrative_domain) == 'administrativedomain' refers to non-existent record: 10106,mos-pma-pta-pta1-sw01#10106,True,,administrativedomain,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.2,,,,,,,ZB.AUTO,,
[noc.core.etl.loader.base] [RS|managedobject] ERROR: Field #4(administrative_domain) == 'administrativedomain' refers to non-existent record: 10107,mos-pma-lta-lta1-sw01#10107,True,10107,administrativedomain,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.4,,,,,,,ZB.AUTO,,

Определение и проверка изменений

Проверка выгруженных данныч выполняется командой ./noc etl check REMOTE_SYSTEM_NAME. Происходит проверка файла import.csv на правильность структуры и связей.
Возможные ошибки:

  • Отсутствует объект по ссылке
[noc.core.etl.loader.base] [RS|managedobject] ERROR: Field #4(administrative_domain) == 'administrativedomain' refers to non-existent record: 10106,mos-pma-pta-pta1-sw01#10106,True,,administrativedomain,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.2,,,,,,,ZB.AUTO,,
[noc.core.etl.loader.base] [RS|managedobject] ERROR: Field #4(administrative_domain) == 'administrativedomain' refers to non-existent record: 10107,mos-pma-lta-lta1-sw01#10107,True,,administrativedomain,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.4,,,,,,,ZB.AUTO,,

Расшифровывается, что поле administrative_domain ссылается на несуществующую запись в выгрузке с administrativedomain (на это указывает поле из mapped_fields) c ID administrativedomain

  • Неправильный формат загрузки

Команда ./noc etl diff REMOTE_SYSTEM_NAME <ExtractorNAME> позволяет увидеть разницу между последней успешной и текущей загрузками. В построчно формате с указателями:

  • / - изменение
  • + - новый объект
  • - - удаление объекта
--- RS.admdiv
--- RS.networksegmentprofile
+ zb.default,zb.default
--- RS.networksegment
+ !new,,Новые,,zb.default
+ !rej,,Отсев,,zb.default
+ !tgfake,,tgfake,,zb.default
--- RS.container
+ 10107,ZabbixHost,PoP | Access,,0,60.646729,56.852081,Екатеринбург, ул. Мира 4
--- RS.resourcegroup
--- RS.managedobjectprofile
+ zb.core.sw,zb.core.sw,35
+ zb.std.sw,zb.std.sw,25
--- RS.administrativedomain
+ zb.root,Заббикс,
--- RS.authprofile
+ ZB.AUTO,ZB.AUTO,,S,,,,,
+ snmp.default,snmp.default,,G,,,,public,
--- RS.ttsystem
--- RS.managedobject
+ 10106,mos-pma-pta-pta1-sw01#10106,True,,zb.root,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.2,,,,,,,ZB.AUTO,
+ 10107,mos-pma-lta-lta1-sw01#10107,True,10107,zb.root,default,!new,Generic.Host,zb.std.sw,,,2,192.168.3.4,,,,,,,ZB.AUTO,
--- RS.link
--- RS.subscriber
--- RS.serviceprofile
--- RS.service

Есть дополнительный ключ - summary позволяет посмотреть суммарное число изменений:
./noc etl diff --summary REMOTE_SYSTEM_NAME <ExtractorNAME>

              Loader |      New |  Updated |  Deleted
              admdiv |        0 |        0 |        0
networksegmentprofile |        1 |        0 |        0
      networksegment |        3 |        0 |        0
           container |        1 |        0 |        0
       resourcegroup |        0 |        0 |        0
managedobjectprofile |        2 |        0 |        0

Выгрузка (Извлечение)

Выполняется командой ./noc etl extract REMOTE_SYSTEM_NAME <EXTRACTOR_NAME>, где:

  • REMOTE_SYSTEM_NAME - имя внешней системы, указанное на предыдущем шаге
  • <EXTRACTOR_NAME> - опциональное имя модели для загрузки

При этой команде произойдёт подключение к внешней системе, забор информации с неё и формирование файлов import.csv по пути: <etl_path>/remote_system_name/loader_name/

Термины

  • Внешняя система (Remote System) - Система, являющаяся источником данных для работы ETL
  • Extractor - Адаптер выгрузки, отвечающий за извлечение информации из Внешней системы, преобразование её к необходимому для работы формату. Итогом работы является файл import.csv
  • Loader - адаптер загрузки (заливки). На основании файла с выгрузкой (import.csv) создаёт объекты в НОКе
  • mappings.csv  файл привязки между ID (ID НОКа <> ID внешней системы)

Реализация адаптера на примере Zabbix

Для примера, реализуем загрузчик данных из Zabbix. Перед началом реализации необходимо посмотреть - какую информацию может выдать внешняя система. В этом плане заббиксе позволяет:

  • Выгрузить Хосты с IP адресами и инвентарной информацией. На их основе есть возможность создать “Объекты управления” (ManagedObject) и контейнеры с геоинформацией (в Инвентори есть поле location)
  • Выгрузить Группы. На основе групп можно будет проводить фильтрацию объекты по правильным профилям.

Также Zabbix поддерживает 2 варианта доступа к данным:

  1. API (при помощи WEB API)
  2. Прямой доступ к базе (есть возможность выдать прямой доступ к БД Zabbix)

Воспользуемся вариантов взаимодействия через API. Адаптер можно посмотреть: Файл адаптера выгрузки Zabbix.

Для настройки адаптера сохраним файл в одном из 2 мест:

  1. contrib/share/zabbix.py. В этом случае строчка Handlers будет выглядеть как: noc.contrib.share.zabbix.ZBRemoteSystem.
  2. <custom_path>/etl/extractors/zabbix.py - в этом случае строчка Handlers в настройках будет выглядеть: noc.custom.etl.extractors.zabbix.ZBRemoteSystem

В каждой папке пути необходимо поместить файл __init__.py:


Адаптер требует установленного пакета py-zabbix. Для этого в паке NOCа выполняем: ./bin/pip install py-zabbix

  1. В меню MainSetupRemote Systems WEB интерфейса добавляем внешнюю систему н-р ZABBIX. Отмечаем галочки на реализованных загрузчиках и прописываем в настройках URL, пользователя и пароль:
  2. В папке НОКа выдаём команду ./noc etl extract ZABBIX. Ожидаем окончания выгрузки.
  3. Командой ./noc etl check ZABBIX. Проверяем отсутствие ошибок.
  4. Командой ./noc etl diff ZABBIX смотрим выгруженные объекты.
  5. ./noc etl load ZABBIX запускает заливку объектов.




  • No labels