Обогащение

Процесс обогащение

Описать алгоритм обогащения. Нарисовать схему обогащения, которая описывает последовательность вызовов настраиваемых компонент:

фетчеров
парсеров
пост процессоров

Схема должна включать этапы:

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

Создание, изменение, удаление КЕ

Описать все ситуации, которые возникают в процессе обогащения:

создание,обновление КЕ
- в какой момент срабатывают правила идентификации
- что такое конфликтные ке
- как разрешаются конфликты
- восстановление КЕ их удаленных
удаление КЕ
- как принимается решение об удалении КЕ
- двухэтапный процесс удаления:
  - пометка на уделения
  - физическое удаление
создание связи
удаление связи
изменение значения атрибута
- атрибут не имел значения - в ходе обогащения появляется новое значение
- атрибут имел значение - в ходе обогащения появляется новое значение
- атрибут имел значение - в ходе обогащения значение исчезает

Исключительные ситуации во время обогащения

Описать какие они бывают:

ошибка
предупреждение

Описать на каких этапах обогащения могут произойти:

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

Описать как с ними можно работать - Итоги обогащения

События обогащения

Описать какие события возникают во время обогащения:

пользовательские события
- начало обогащения
- заверение обогащение
  - какую инфомрацию оно несет:
    - длительность обогащения
    - количество
    - цвет от чего зависит
- промежуточная стадия обогащения (если актуально)
события статистики:
- назначение события
- место публикации
- ключи маршрутизации
- тело события

Обогащение по расписанию

Описать настройку обогащения по расписанию

Уведомления по время обогащения

Описать какие уведомления генерируются в процессе обогащения

Фетчеры

Фетчер - это компонент или модуль, который отвечает за получение (fetch) данных из внешних источников.

Наследование параметров фетчеров

Благодаря наследованию CMDB выполняет автоматическую привязку атрибутов в дереве ТКЕ. Однако, для обогащения сами атрибуты привязать недостаточно. На них нужно настроить фетчеры. Настройка фетчеров подчиняется правилам наследования. Поведение наследования зависит от того в каком месте иерархической цепочки выполняется настройка. В общем виде правила наследования выглядят следующим образом:

Настройка фетчера распространяется на все атрибуты дочерних ТКЕ
На дочернем ТКЕ фетчер может быть переопределен
Переопределение может быть удалено, фетчер восстановит настройку родителя
Фетчер самостоятельно не может перейти из настроенного/переопределенного состояния в унаследованное, даже если его настройки совпадают с родительским фетчером

Настройка фетчера на корневом атрибуте

Настройка фетчера на атрибуте корневого ТКЕ приведет к тому, что настройка распространится на все

Получить данные из атрибута

Предназначен для получения данных из значения атрибута КЕ. Настраиваемый параметр: атрибут из которого взять данные - наименование атрибута ТКЕ.

Получить данные из конфигурации

Предназначен для получения конфигурации КЕ во время обогащения.

Сохранить значение в атрибут

Предназначен для заполнения атрибута КЕ определенным значением. Настраиваемый параметр: данные, которые нужно записать в атрибут - строка.

Выполнить HTTP GET запрос

Предназначен для получения данных по HTTP. Настраиваемые параметры:

параметры запроса- строка;
проверить TLS сертификат сервера - флаг включающий проверку TLS сертификата сервера;
использовать ТКЕ для подстановки данных из атрибутов - Не использовать или наименование ТКЕ;
имя хоста - строка или наименование атрибута ТКЕ;
порт - число или наименование атрибута ТКЕ;
логин - строка или наименование атрибута ТКЕ;
пароль - строка или наименование атрибута ТКЕ;
путь - строка или наименование атрибута ТКЕ;

Выполнить SSH команду

Предназначен для получения данных по ssh. Настраиваемые параметры:

команда выполняемая на устройстве - строка;
использовать ТКЕ для подстановки данных из атрибутов - Не использовать или наименование ТКЕ;
имя хоста - строка или наименование атрибута ТКЕ;
порт - число или наименование атрибута ТКЕ;
логин - строка или наименование атрибута ТКЕ;
пароль - строка или наименование атрибута ТКЕ;
цифровой отпечаток - строка или наименование атрибута ТКЕ;

Опросить DionisNX

Предназначен для взаимодействия с DionisNX по ssh. Настраиваемые параметры:

действие - Получить конфигурацию или Выполнить команду;
конфигурации - running или startup;
команда - строка или наименование атрибута ТКЕ;
использовать ТКЕ для подстановки данных из атрибутов - Не использовать или наименование ТКЕ;
имя хоста - строка или наименование атрибута ТКЕ;
порт - число или наименование атрибута ТКЕ;
логин - строка или наименование атрибута ТКЕ;
пароль - строка или наименование атрибута ТКЕ;
цифровой отпечаток - строка или наименование атрибута ТКЕ;

Отпечаток ключа

Предназначен для получения ssh отпечатка. Настраиваемые параметры:

использовать ТКЕ для подстановки данных из атрибутов - Не использовать или наименование ТКЕ;
имя хоста - строка или наименование атрибута ТКЕ;
порт - число или наименование атрибута ТКЕ;

Получить авторизационные данные из запроса

Предназначен для получения авторизационных данных из HTTP запроса. Настраиваемые параметры:

формат HTTP запроса - JavaScript формат или Yaml формат;
проверить TLS сертификат сервера - флаг включающий проверку TLS сертификата сервера;
данные HTTP запроса для авторизации - текст;
данные HTTP запроса для проверки/продления актуальности данных - текст;

Пример параметра данные HTTP запроса для авторизации в JavaScript формате:

fetch("http://example.com/test?id=8&name=t", {
  "headers": {
    "content-type": "application/json",
    "cookie": "params=1; session=123"
  },
  "body": "{\"arguments\":{\"attribute_name\":\"raw_configuration\"}}",
  "method": "PUT"
});

Пример параметра данные HTTP запроса для проверки/продления актуальности данных в Yaml формате:

url: http://example.com/test
params:
  id: 8
  name: t
headers:
  content-type: application/json
  cookie: params=1; session=123
body:
  arguments:
    attribute_name:raw_configuration
method: PUT

Правила заполнения параметров

Поле для параметров данные HTTP запроса для авторизации и данные HTTP запроса для проверки/продления актуальности данных поддерживают шаблонизатор jinja.

Используются следующие правила:

[% - начало блока;
%] - конец блока;
[# - начало коментария;
#] - конец коментария;
[[ - начало переменной;
]] - конец переменной.

Поддерживаются следующие конструкции:

[[ attributes.<имя_атрибута> ]] - ссылка на значение атрибута;
[[ composition.<имя_ТКЕ>.attributes.<имя_атрибута> ]] - ссылка на значение атрибута композирующего КЕ;
[[ fields.ci_id ]] - ссылка на идентификатор текущего КЕ;
[[ fields.ci_type_name ]] - ссылка на имя ТКЕ текущего КЕ;
[[ fields.comp_ci_id ]] - ссылка на идентификатор композирующего КЕ.

Поддерживаются следующие ключи:

url - только в Yaml формате;
params;
headers;
body;
method;

Ключ method поддерживает следующие значения:

GET;
OPTIONS;
HEAD;
POST;
PUT;
PATCH;
DELETE.

Выполнить HTTP запрос

Предназначен для получения данных по HTTP. Настраиваемые параметры:

формат HTTP запроса - JavaScript формат или Yaml формат;
запомнить возвращенную cookie в глобальном хранилище - флаг;
проверить TLS сертификат сервера - флаг включающий проверку TLS сертификата сервера;
данные HTTP запроса для авторизации - текст, поддерживает шаблонизатор jinja аналогично фетчеру Получить авторизационные данные из запроса;

Cell tower fetcher

Предназначен для получения усреднённых координат на основании данных о вышках сотовой связи. Входные данные представляют собой список объектов, содержащих информацию о вышках, включая их координаты и идентификаторы.

Настраиваемый параметр: атрибут из которого взять данные - наименование атрибута ТКЕ, из которого будут извлекаться данные.

Данные в атрибуте должны быть представлены в виде списка объектов со следующими полями:

act - (опционально) активность;
mcc - (опционально) код страны;
mnc - (опционально) код оператора;
area - (опционально) код зоны;
cell - (опционально) код ячейки;
lon - (опционально) долгота вышки;
lat - (опционально) широта вышки; Все поля не обязательны, но хотя бы одно из них должно быть заполнено. Лишние поля игнорируются.

Пример json схемы для атрибута:

{
  "type": "array",
  "items":{
      "type": "object",
      "properties": {
        "act": {
          "type": "string"
        },
        "mcc": {
          "type": "integer"
        },
        "mnc": {
          "type": "integer"
        },
        "area": {
          "type": "integer"
        },
        "cell": {
          "type": "integer"
        },
        "lon": {
          "type": "number"
        },
        "lat": {
          "type": "number"
        }
      }
    }
}

Пример данных в атрибуте:

[{
  "act": 123,

  "mcc": 123,
  "mnc": 123,

  "area": 123,
  "cell": 123,

  "lon": 123.123,
  "lat": 123.123
}]

В результате работы фетчер возвращает следующую структуру:

{
  "lat": 123.23,
  "lon": 123.23,

  "precision": 10,
}

Логика работы фетчера

Группировка данных: Входные данные группируются по уровню точности, от более точных к менее точным.
Усреднение координат: Усреднение выполняется только в пределах одной группы. Выбирается группа с наивысшей точностью. Внутри группы координаты берутся из базы данных вышек с учетом имеемой информации о вышке в текущей группе. Чем меньше информации о вышке тем больше вариантов получится при сопоставлении с базой данных, тем меньше точность результата.
Определение точности: Точность результата зависит от полноты данных о вышке. Значение точности указывается в поле precision.

Уровни точности

10: Используются поля lon и lat.
9: Используются поля act, mcc, mnc, area, cell.
8: Используются поля mcc, mnc, area, cell.
7: Используются поля act, mcc, mnc, area.
6: Используются поля mcc, mnc, area.
5: Используются поля act, mcc, mnc.
4: Используются поля mcc, mnc.

Примеры работы

Пример 1:

Входные данные:

[{
  "act": 123,

  "mcc": 123,
  "mnc": 123,

  "area": 123,
  "cell": 123,

  "lon": 123.123,
  "lat": 123.123
}]

Результат:

{
  "lat": 123.123,
  "lon": 123.123,

  "precision": 10,
}

Пример 2:

Входные данные:

[{
  "act": 123,

  "mcc": 123,
  "mnc": 123,

  "area": 123,
  "cell": 123,
}]

Результат(координаты получены из базы данных вышек):

{
  "lat": 123.123,
  "lon": 123.123,

  "precision": 9,
}

Требования к данным

Для работы фетчера необходима база данных координат вышек сотовой связи. Архив с координатами сервера доступен по ссылке https://nexus.pamir.int/#browse/browse:pamir-configs:cell_towers.sqlite.

Настройки окружения

Скачайте архив и разместите его в локальном хранилище.
Пробросьте архив в контейнер celery, указав путь к файлу в переменной окружения CELL_TOWERS_SQLITE_PATH По умлочанию (без указания переменной) файл ищется по пути /opt/tenax-it/cell_towers/cell_towers.sqlite.

Пример проброса архива в контейнер (если архив с вышками лежит в папке ./data/cell_towers):

# docker-compose.celery.app.yml в контейнере:
  - type: bind
    source: ./data/cell_towers
    target: /opt/tenax-it/cell_towers

Требования к данным

Настройки окружения

Скачайте архив и разместите его в локальном хранилище.
Пробросьте архив в контейнер celery, указав путь к файлу в переменной окружения CELL_TOWERS_SQLITE_PATH По умлочанию (без указания переменной) файл ищется по пути /opt/tenax-it/cell_towers/cell_towers.sqlite.

Пример проброса архива в контейнер (если архив с вышками лежит в папке ./data/cell_towers):

# docker-compose.celery.app.yml в контейнере:
  - type: bind
    source: ./data/cell_towers
    target: /opt/tenax-it/cell_towers

Выполнить PromQL запрос

Предназначен для получения данных от Prometheus. Настраиваемые параметры:

атрибут из которого взять данные- Использовать литеральное значение или наименование атрибута ТКЕ;
значение - текст;
проверить TLS сертификат сервера - флаг включающий проверку TLS сертификата сервера;

Парсеры

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

Наследование параметров парсеров

Наследование параметров парсеров выполняется аналогично фетчерам

JQ parser

Парсер предназначен для извлечения данных из JSON конфигурации, при помощи языка jq. Аргументы парсера - это список JQ выражений и методов. Парсер поочереди выполняет выражения, до первого совпадения. Аргументы парсера:

выражение - строка описывающая JQ выражение, поддерживает шаблонизатор jinja;
метод поиска - текст, все совпадения или первое совпадение;
постпроцессоры - список постпроцессоров.

Например, корневым элементом конфигурации является список:

[1, 2, 3]

В этом случае выражение [# jinja2 comment #] .[]+5 вернет:

6\n7\n8 - результат метода текст;
[6, 7, 8] - результат метода все совпадения;
6 - результат метода первое совпадение.

JSON

Парсер предназначен для извлечения данных из JSON конфигурации, при помощи библиотеки python objectpath. Аргументы парсера:

выражение - строка описывающая Objectpath выражение;
группировать по - поле по которому происходит группировка, например @.field. Группа представляет собой массив. Задается в виде фильтра для json path, который можно применить после выполнения выражения.
постпроцессоры - список постпроцессоров.

Например, корневым элементом конфигурации является объект:

{
    "str_val": "asc",
    "int_val": 123,
    "str_list_val": ["asc","desc"],
    "dt_val": "2023-10-19 12:00:00",
    "bool_val": true,
    "jb_val": {"val": true, "list": ["asc",123,false]},
    "obj_list": [{"key": "one", "val": "first"}, {"key": "two", "val": "second"}]
}

В этом случае выражения могут быть следующие:

$.bool_val - выбор элемента по ключу, вернет результат true;
$.obj_list[0].val - выбор элемента списка по индексу, вернет результат first;
$.obj_list[@.key is 'one'][0].val - выбор элемента списка по условию, вернет результат first.

Например, корневым элементом конфигурации является список:

[
    {"key": "one", "val": "first"},
    {"key": "two", "val": "second"}
]

В этом случае выражения могут быть следующие:

$*[0].val - выбор элемента списка по индексу, вернет результат first;
$*[@.key is 'one'][0].val - выбор элемента списка по условию, вернет результат first.

Цепочка регулярных выражений

Парсер поочереди выполняет регулярные выражения, результаты помещенные в группы по одному передаются на вход следующего регулярного выражения. Аргументы парсера:

список регулярных выражений - список регулярных выражений, поддерживаемых python;
постпроцессоры - список постпроцессоров.

Регулярное выражение с именованными группами

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

список регулярных выражений - список регулярных выражений с именованными группами, поддерживаемых python.

Например, для конфигурации списка правил доступа:

ip access-list no-web
 deny tcp dport www
 deny tcp sport www
 permit icmp

Список регулярных выражений может быть таким:

^ (?P<rule>\S+) (?P<proto>\S+) (?P<dest>\S+) (?P<port>\S+)$ - выбираем правила из 4 слов;
^ (?P<rule>\S+) (?P<proto>\S+)$ - выбираем правила из 2 слов.

Регулярное выражение

Парсер находит вхождения для регулярного выражения. Аргументы парсера:

регулярное выражение - регулярное выражение, поддерживаемое python;
метод поиска - все совпадения (с номерами строк), все совпадения или первое совпадение;
тип разделителя после номера строки - пробел или литеральное значение;
разделитель номера строки - строка;
постпроцессоры - список постпроцессоров.

Постпроцессоры

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

True постпроцессор

Постпроцессор предназначен для сравнения полученного парсером результата с ожидаемым значением. Если результат парсера совпадает с ожидаемым значением, то возвращается True (истина), иначе результат возвращается без изменений. Аргументы постпроцессора:

ожидаемое значение - строка.

False постпроцессор

Постпроцессор предназначен для сравнения полученного парсером результата с ожидаемым значением. Если результат парсера совпадает с ожидаемым значением, то возвращается False (ложь), иначе результат возвращается без изменений. Аргументы постпроцессора:

ожидаемое значение - строка.

Постпроцессор строки времени

Постпроцессор предназначен для преобразования строки времени в строку времени в соответствии с аргументами. Аргументы постпроцессора:

шаблон - возвращаемый формат, поддерживаемый python, например %Y-%m-%d %H:%M:%S;
временная зона - временная зона заданная строкой формата HH:MM:00, где HH - часы, а ММ - минуты;
временной сдвиг - плюс или минус. Особенности работы: Аргумент временная зона заполнять не обязательно. В этом случае применяется временная зона сервера Памир и аргумент временной сдвиг не обрабатывается. Например:
обрабатываемая строка: 2025-05-09 11:00:00
шаблон: %Y-%m-%d %H:%M:%S
временная зона: незаполнено
результат: 2025-05-09T11:00:00+03:00 Если в шаблоне используются параметры временной зоны %Z или %z, и заполнен аргумент временная зона, то в обработке будет использоваться значение аргумента временная зона. Например:
обрабатываемая строка: 2025-05-09 11:00:00 UTC +0500
шаблон: %Y-%m-%d %H:%M:%S %Z %z
временная зона: 03:00:00
временной сдвиг: плюс
результат: 2025-05-09T11:00:00+03:00

Постпроцессор метки времени

Постпроцессор предназначен для преобразования времени из секунд или миллисекунд прошедших с 01.01.1970 в строку формата YYYY-MM-DD HH:MM:SS+HH:MM. Аргументы постпроцессора:

единица измерения - секунды или миллисекунды.

Постпроцессор подстановки значения

Постпроцессор предназначен для замены полученного парсером результата, на значение из списка пар "ключ": "значение". Если результат парсера совпадает с ключом в списке, то возвращается соответствующее ключу значение, иначе результат возвращается без изменений. Аргументы постпроцессора:

ключ - ожидаемое значение;
значение - новое значение.

Процесс обогащение​

Создание, изменение, удаление КЕ​

Исключительные ситуации во время обогащения​

События обогащения​

Обогащение по расписанию​

Уведомления по время обогащения​

Фетчеры​

Наследование параметров фетчеров​

Получить данные из атрибута​

Получить данные из конфигурации​

Сохранить значение в атрибут​

Выполнить HTTP GET запрос​

Выполнить SSH команду​

Опросить DionisNX​

Отпечаток ключа​

Получить авторизационные данные из запроса​

Правила заполнения параметров​

Выполнить HTTP запрос​

Cell tower fetcher​

Выполнить PromQL запрос​

Парсеры​

Наследование параметров парсеров​

JQ parser​

JSON​

Цепочка регулярных выражений​

Регулярное выражение с именованными группами​

Регулярное выражение​

Постпроцессоры​

True постпроцессор​

False постпроцессор​

Постпроцессор строки времени​

Постпроцессор метки времени​

Постпроцессор подстановки значения​