Аннотация

В настоящем документе описываются действия оператора при работе с универсальной модульной интеграционной Платформой «СинГраф» (далее Платформа).

В разделе «Назначение программы» указаны сведения о назначении программы и информация, достаточная для понимания функций программы и её эксплуатации.

В разделе «Условия выполнения программы» указаны сведения о технических и программных средствах, обеспечивающих выполнение данной программы.

В разделе «Возможные подходы к использованию программы» приведено описание работы с программой.

Назначение программы

Платформа СинГраф представляет собой программный комплекс, предназначенный для создания функциональных моделей многоуровневых слабосвязанных систем c динамично меняющимися структурами и процессами.

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

Платформа строится на основе программного решения, представляющего собой реализацию функциональной графовой модели. Оно представляет собой графовую БД с возможностью запуска асинхронных функций по serverless модели, причем встроенный граф используется:

● для хранения данных,

● в качестве пути для обмена сообщениями между функциями, работающими на вершинах графа.

Рис. 1 Назначение Платформы

Технические и программные средства, обеспечивающие выполнение программы

Платформа СинГраф устанавливается на серверы управления, к которым предъявляются следующие минимальные технические требования:

Функциональные особенности программы

Графовая база данных и функциональный граф

СинГраф использует вершины графа для хранения данных и ребра графа для связи между объектами. Эти ребра также служат средством хранения данных. Функции могут запускаться входящими сигналами, обращенными к вершинам, и использовать ребра для вызова функций в соседних вершинах.

Информация и метаданные в одном графе

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

Распределенная шина событий

СинГраф использует асинхронную систему событий, в которой все сигналы представлены как события в различных темах внутри кластеризованной шины событий. Шина событий является постоянной и реализует метод обработки сигналов exactly once.

Распределенная асинхронная рабочая среда

Рабочая среда приложения состоит из асинхронных функций, вызываемых объектами. Бизнес-логика определяется посредством вызова цепочек сигналов, которые реализуют различные варианты ее использования. Функции могут быть распределены как географически, так и логически, что обеспечивает гибкость работы.

Бессерверные функции с отслеживанием состояния

Функции, отслеживающие состояние СинГраф, распределены по многочисленным средам выполнения, подключенным к общей сети, что устраняет необходимость в централизованном управлении. Каждый экземпляр stateful-функции имеет свой собственный постоянный контекст, что позволяет ему хранить данные между вызовами.

Постоянное хранение

Контексты выполнения функций являются постоянными и хранятся асинхронно в центральном базовом кластере. Их можно восстановить в случае сбоя или перемещения функций или приложений. Каждая функция имеет выделенный контекст для каждого объекта (вершины графа).

Граф как путь сигнала

Графы вСинГраф служат не только моделями данных, но и средством передачи сигналов от одного объекта к другому. Сигналы могут пересекать одно или несколько ребер, в зависимости от типов и атрибутов ребер.

Удобная среда выполнения

Функции могут запускаться непосредственно на контроллерах объектов, таких как BMC, PLC, RPi и т. д. Вызовы функций направляются в соседние среды выполнения, работающие на соответствующих контроллерах.

Высокая производительность

СинГраф способен обрабатывать до 400 000 вызовов функций в секунду на сервере среднего размера. Масштабируемость практически линейна за счет кластеризации.

XPath-подобный язык запросов для обхода графов и распределения сигналов

СинГраф предоставляет язык запросов для определения запросов к графам, позволяя исследовать графы, обнаруживать объекты и определять маршруты обхода для распределения сигналов, а также для других приложений.

Совместная работа приложений и расширение функциональной модели графа

Приложения могут сосуществовать и взаимодействовать, используя одну и ту же модель данных графа, и взаимодействовать через ребра графа. Такое повторное использование модели данных расширяет возможности повторного использования кода.

Словарь

Панель управления СинГраф. Набор инструментов и технических возможностей Платформы, позволяющий создать универсальную управляющую модель для интегрированных с Платформой внешних систем и внедрить функционал, описанный в разделе “Функциональность” данного документа.

Функции с контролем состояния. Особый тип функций, которые могут быть вызваны с помощью очереди NATS отправкой сигнала, которая обычно сопровождается публикацией сообщения. Уникальным идентификатором такой функции является typename, используемый и как имя, и как адрес в графе. Вызов функции с контролем состояния всегда содержит идентификатор очереди, содержащий информацию об объекте или сущности внутри системы. В случае если функция с контролем состояния вызывается с тем же идентификатором одновременно, она исполняется последовательно, чтобы

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

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

Обратите внимание: NATS - брокер сообщений, дающий возможность обмена сообщениями как в формате публикация-подписка, так и в в формате запрос-ответ.

Приложение. Приложение на Платформе СинГраф представляет собой набор функций с контролем состояния, выполняемых в распределенной среде исполнения. Эти функции должны быть разработаны и оркестрированы с учетом требований к поведению и функциональным возможностям системы.

Адаптер. Задача адаптера на Платформе СинГраф - обеспечить взаимодействие конкретного приложения Платформы с внешними системами и сервисами. Слой адаптеров обеспечивает для приложений бесшовную интеграцию с внешней средой и является частью платформенного графа, упрощая взаимодействие.

Сигнал. Сигнал передает имя функции с сохранением состояния. Отправка сигнала, обозначенного как S к объекту, обозначенному как O, по сути дела запускает выполнение функции с сохранением состояния, чьим ID выступает имя S, по отношению к объекту O.

Имя функции с сохранением состояния. Это уникальное название, присвоенное функции. Оно также служит адресом функции в пределах функционального пространства. Наличие уникального имени для каждой функции в приложении на Платформе СинГраф позволяет выполнять прямой вызов этой функции либо адресацию к ней.

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

Объект. В контексте Платформы СинГраф объект - это вершина в структуре системного графа. Такая вершина содержит всю доступную информацию о каком-либо объекте или явлении в реальном мире, предоставляя средства для моделирования и взаимодействия с объектами реального мира внутри системы.

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

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

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

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

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

Выполнение программы

Правила отображения информации в графе

Данные графа о системе должны храниться в унифицированной форме как показано на рисунке ниже.

1. Корень вершины

ID корня - “root”. Корень присутствует в графе всегда. Корень - это точка входа в граф. Из него всегда выходят только два линка:

1. Линк типа “__types” ведет к вершине с ID “types”.
2. Линк типа “__objects” ведет к вершине с ID “objects ”.

Наличие тела для такой вершины не обязательно.

2. Вершины типов

ID вершины - “types”. Из нее выходят линки “ __type”, ведущие ко всем вершинам, которые представляют типы объектов. У каждого линка должен быть тэг типа “name_<to_type_name>”, где “to_type_name” - это название типа объектов, к которому ведет линк.

Наличие тела для такой вершины не обязательно.

3. Группа вершин типов

Существует только в том случае, если группировка задана. Отмечается типом “group”. Из такой вершины выходят линки “ __object”,направленные ко всем вершинам объектов, входящим в группу. Также такая вершина всегда имеет выходящий линк, направленный на нее же (т.е. в форме петли), что отображает способность объектов типа “group” связываться друг с другом, формируя новые группы. Из такой вершины могут также выходить линки к другим вершинам типов.

4. Вершина типа

Пример такой вершины сервер, диск, группа (см Рис. 1). Вершина содержит все данные о соответствующем типе объектов. Из нее выходят линки “ __object”, направленные ко всем вершинам объектов соответствующего типа. Также из нее могут выходить линки к вершинам других типов.

Такая вершина может иметь тело, в котором отображаются метаданные и правила для соответствующего типа объектов.

5. Вершины объектов

Из каждой вершины с ID “objects” выходят линки с типом “ __object”, направленные ко всем вершинам, представляющим объекты. Каждый из этих линков должен иметь тег “name_<to_object_name>”, где “to_object_name” содержит имя объекта, к которому направлен линк. Дополнительных данных в теле вершины не требуется.

6. Навигация между вершинами объектов

Эта вершина представлена в графе только в том случае, если топология предполагает навигацию. Она представляет особый объект типа group. Из такой вершины выходят линки, направленные ко всем вершинам объектов типа group (в теле линка это обозначено как group->group), в совокупности они представляют собой точки входа в топологию. Кроме того, из такой вершины всегда выходит линк в вершину типа group. Из навигационной вершины также могут выходить линки к другим вершинам типов. Она служит точкой входа для навигации по топологии с помощью языка запросов JPGQL.

7. Вершина объекта

В качестве примера такой вершины на Рис.1 можно указать вершины server1, disk1 и nav. Эти вершины содержать всю информацию о представляемых ими объектах. Из каждой вершины выходит линк типа __type, он направлен к вершине типов, которая представляет соответствующий тип объектов. Кроме того, из вершин объектов могут выходить линки, направленные к другим вершинам объектов. Тип линка от вершины объекта А к вершине объекта В должен быть описан в теле линка от типа объектов TypeA к типу объектов TypeB. В теле каждой вершины объекта содержится вся необходимая информация о представляемом объекте.

Внешнее API

Доступ к API приложения СинГраф из внешних систем возможен с помощью вызова stateful-функции, позволяющей получить ответ в случае, если таковой был отправлен. Запросы и ответы передаются в JSON-формате. Есть два способа вызова функции.

1. Сигнал - асинхронный вызов функции с возможностью получить ответ (если он заложен в коде функции) to a predefined topic known as "egress".

2. Запрос – синхронный вызов функции с возможностью получить ответ (если он заложен в коде функции) после выполнения вызова.

Описание функции

В некоторых приложениях Платформы присутствует функция с именем functions.app.api.test. В результате выполнения она возвращает ответы и на синхронные, и на асинхронные вызовы:

Если при конфигурации функции задано значение SetAllowedRequestProviders(sfPlugins.AutoRequestSelect), это означает, что такая функция способна выполнять синхронные запросы, а не только отправлять асинхронные сигналы.

Вызов и получение ответа

• Адреса

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

• Сигнал

Формат сообщения для передачи сигнала к любой функции: signal.<function_typename>.<id>

Для функции из примера выше сообщение будет выглядеть как signal.functions.app.api.test.foo, где foo - идентификатор объекта, относящийся к функции, работающей с данным объектом.

• Отправка

Формат сообщения для передачи ответа на полученный сигнал от функции (если это предусмотрено ее логикой):

Для функции из примера выше сообщение будет выглядеть так:

• Запрос

Формат сообщения для передачи сигнала к произвольной функции:

Для функции из примера выше сообщение будет выглядеть так:

• Payload

Чтобы вызвать эту функцию любым из способов (сигналом или запросом), как и любую другую функцию Платформы, следует отправить в ее адрес JSON такого вида:

В качестве ответа (если он предусмотрен), также будет возвращен JSON, структура которого также целиком зависит от вызванной функции.

Способы вызова функций

Рассмотрим способы вызова функции через утилиту командной строки NATS.

Signal

1. Подпишитесь на сообщения, чтобы дождаться ответа:

2. Отправьте сигнал функции:

Запрос

Синхронный вызов функции:

Операции создания, удаления, редактирования и чтения в графе

1. Подпишитесь и получите ответное сообщение:

2. Вызовите одну из функций, перечисленных ниже.

3. Чтобы записать логи объекта со всеми его линками, используйте функцию:

Например:

Проверьте nats KV store через io container:

Функции

Создание объекта

Пример:

Редактирование объекта

Пример:

Удаление объекта

Пример:

Создание линка

Пример:

Редактирование линка

Пример:

Удаление линка

Пример:

Язык запросов JPGQL

Для формирования запросов на платформе используется JPGQL. Это облегченный язык асинхронных и параллелизованных запросов для графа, похожий на JSONPath. Сейчас языка находится на начальной стадии разработки, в будущем планируется расширение его функциональности.

Синтаксис

Синтаксис JPGQL следует описанному ниже паттерну:

● level_access может быть одной из констант:

- ○ . со следующего уровня

- ○ .. с любого уровня for any level (first occurrences on all roots only)

● link_name текстовое значение, допускается использование символов: a-z A-Z_-

● filter значение в квадратных скобках, добавляется к фильтруемым выражениям.

Ограничения

1. Не используйте символы $ и @ в фильтре.
2. Фильтр может содержать только предзаданные функции, связанные символами && и ||.
3. Линк содержит символы: a-zA-Z_-

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

Каждая выходная ссылка вершины имеет свое уникальное имя. Желаемая ссылка должна быть названа согласно определению.

Желаемые ссылки должны содержать все указанные теги.

Примеры

Находит все объекты от целевого через его выходные маршруты, которые удовлетворяют следующим условиям:

Любые ссылки на глубине=1:

Любые ссылки на глубине=1, содержащие тег tag1:

Ссылка типа type1 на глубине=1, содержащая оба тега tag1 и tag2:

Ссылка типа type1 на глубине=1, содержащая оба тега tag1 и tag2 на глубине=2, за которой следует ссылка с именем name1:

Полный адрес вершины через имена name1, name2 и name3:

Ссылки на любой глубине, содержащие оба тега tag1 и tag2:

Маршруты, которые проходят через ссылку типа type1 на глубине=1 и через любую ссылку с тегами tag1 и tag2 на любой большей глубине:

Маршруты, которые проходят через ссылки типа type1 на глубине=4:

При использовании команды nats pub двойные кавычки вокруг тега должны быть экранированы из-за вложенных кавычек. Либо используйте одиночные кавычки 'tag', либо тройное экранирование \\\"tag\\\".

Например:

Как написать приложение для СинГраф

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

• Вы можете создать эти объекты прямо в разрабатываемом вами приложении, например, на этапе начальной загрузки.
• Вы также можете импортировать объекты из другого приложения СинГраф, используя адаптер.

3. Разработайте функции с отслеживанием состояния:

• создайте все необходимые функции, которые сформируют ядро вашего приложения

4. Внедрите асинхронную коммуникацию:

• Подготовьте эти функции к работе в асинхронном режиме с использованием вызовов, которые обрабатываются NATS нужным вам образом.
• Используйте контекст СинГраф для хранения данных между вызовами.
• Рассмотрите возможность использовать контекст объекта для работы с данными о нем.

Оценка производительности

Ниже описаны индикаторы производительности для разных типов операций на Платформе СинГраф. Чтобы измерить производительность, воспроизведите следующие шаги:

1. Отправьте в сообщения в NATS во время выполнения функций с сохранением состояния, чтобы измерить их производительность.
2. Запустите приложение.
3. Используйте docker logs для просмотра логов работы приложения.

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

Мастер-функция

JavaScript отключен.

JPGQL_DCRA

Выполните поиск по графу на глубину =3 по тегам

Операции CRUD в графе

Создать объект

Отредактировать объект

Создать линк от корня объекта к объекту А

Редактировать линк от корня объекта к объекту А

Сообщения оператору

Программное обеспечение СинГраф в ходе настройки, проверки и функционирования может выдавать ряд сообщений, которые сохраняются в виде записей лог-файлов. Перечень сообщений и их формат подробно описываются в программной документации на ПО Docker, Keycloak.

Справка и помощь

Общая справка

Справка по gwalk

Справка по inspect

Справка по route