Руководство

Расширения / Разработка / Расширения АктивногоШлюза / Руководство

Давайте учиться на примере. В этом уроке мы покажем вам создание базового расширения АктивногоШлюза. Ваше расширение АктивногоШлюза будет выполняться на АктивномШлюзе и позволит отслеживать демонстрационное приложение, входящее в комплект АктивногоШлюза Extension SDK.

Подготовьте свое окружение

1. Проверьте предварительные условия:
   • Ключ-АСТРОМ версии 1.176 или новее
   • Среда АктивногоШлюза. Чтобы запускать расширения с АктивнымШлюзом, установленным в Amazon Linux 2022, вам необходимо установить библиотеку libxcrypt-compat.
   • Мониторинг доступа администратора
2. Установите Python 3.8. АктивныйШлюз поставляется с Python 3.8. Мы рекомендуем использовать Extension SDK с той же версией Python.
3. Установите среду АктивногоШлюза. В версии 1.175+ модуль плагина установлен по умолчанию.

Загрузите SDK расширения АктивногоШлюза

1. Войдите в Ключ-АСТРОМ, перейдите в «Настройки » > «Отслеживаемые технологии » > «Добавить мониторинг новых технологий » > «Добавить расширение АктивногоШлюза» и нажмите «Загрузить SDK расширения» .
2. Распакуйте архив в удобную директорию. Он содержит документацию, примеры и файл Extension SDK, который whlвы будете использовать для установки SDK.
3. В каталоге вы найдете примеры расширений examples. В этой статье мы будем использовать CustomCloudTechnologyрасширение, расположенное в demo_activegate_plugin_multiкаталоге.

Установите SDK расширения АктивногоШлюза

Виртуальная среда Python

Мы рекомендуем установить Extension SDK с использованием виртуальной среды Python. Инструкции см. в разделе «Виртуальные среды и пакеты».в документации Python.

1. Перейдите в извлеченный каталог с whlфайлом и выполните следующую команду: pip3 install plugin_sdk-[sdk version number]-py3-none-any.whl например pip3 install plugin_sdk-1.156.0.20181003.61122-py3-none-any.whl

1. Запустите plugin_sdk --help, чтобы проверить установку Extension SDK. Дополнительную информацию см. в разделе [Install Extension SDK]plugin-sdk-overview).

Развернуть расширение

То, что нужно запомнить

1. Вы должны загрузить расширение как на сервер КлючАстром, так и на АктивномШлюзе, который будет его выполнять. Если вы установили Extension SDK на хосте АктивногоШлюза, build_pluginкоманда позаботится как о Сервере, так и о АктивномШлюзе. Если вы установили SDK расширения на отдельный хост, что является более распространенным случаем, загрузите расширение в АктивныйШлюз вручную. На этапе разработки мы рекомендуем вам установить Extension SDK на АктивныйШлюз, чтобы упростить процесс разработки.
2. Команда build_pluginсоздает пакет расширения и загружает его в выбранный каталог развертывания. Для запуска команды вам понадобится URL-адрес и токен сервера Ключ-АСТРОМ. Если вы установили Extension SDK на хосте АктивногоШлюза, SDK автоматически получит URL-адрес сервера из конфигурации АктивногоШлюза. Получите токен в разделе «Настройки» > «Отслеживаемые технологии» > «Пользовательские расширения» и сохраните его как plugin_upload.tokenфайл в каталоге конфигурации подключаемого модуля АктивногоШлюза. По умолчанию %PROGRAMFILES%\astromkey\remotepluginmodule\agent\confв Windows и /opt/astromkey/remotepluginmodule/agent/confLinux.
3. Вы не можете развернуть одну и ту же версию расширения дважды. Чтобы загрузить измененное расширение, обязательно увеличивайте версию расширения при каждой сборке или загрузке. Используйте это versionсвойство в разделе метаданных вашего определения JSON .

Разверните свое расширение!

Перейдите в \examples\demo_activegate_pluginкаталог расширения SDK и выполните plugin_sdk build_pluginкоманду. Он создаст пакет расширения из текущего каталога. По завершении скопируйте пакет расширения в каталог развертывания АктивногоШлюза ( %PROGRAMFILES%\astromkey\remotepluginmodule\plugin_deploymentили /opt/astromkey/remotepluginmodule/plugin_deploymentзагрузите расширение на сервер Ключ-АСТРОМ, которому назначен ваш АктивныйШлюз. Подобное сообщение означает, что все прошло хорошо.

Copying plugin to target_directory: {plugin_deployment_dir}\custom.remote.python.example_multi

Creating plugin archive

========================================

Plugin deployed successfully into {plugin_deployment_dir}\custom.remote.python.example_multi

Plugin archive available at {plugin_deployment_dir}\custom.remote.python.example_multi.zip

========================================

interactive upload -> oneagent_upload_plugin -p {plugin_deployment_dir}\custom.remote.python.example_multi.zip -s https://{astromkey_server_URL}:443/api/v1/remoteplugins -t #####################

Attempting to send plugin to server https://{astromkey_server_URL}:443/api/v1/remoteplugins

plugin has been uploaded successfully

Поздравляем, вы успешно развернули свое первое расширение ActiveGate.

Запустите демо-приложение

Ваше первое расширение АктивногоШлюза будет отслеживать демонстрационное приложение, включенное в SDK. Демо-приложение имитирует EXAMPLE_SERVICEтехнологию, работающую в кластере (группе устройств) с двумя узлами (устройствами). API демонстрационного приложения предоставляет доступ к метрикам. Ваше расширение импортирует топологию и получит метрики.

1. Запустите демонстрационное приложение. Перейдите в каталог, в который вы распаковали SDK, и выполните следующую команду: python -m plugin_sdk.demo_app
2. Убедитесь, что ваше приложение запущено и работает. Перейдите http://127.0.0.1:8769/и проверьте ответ приложения.

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

1. Перейдите в «Настройки» > «Отслеживаемые технологии» > вкладка «Пользовательские расширения».
2. Откройте CustomCloudTechnologyрасширение и настройте его.
3. Проверьте успешный запуск расширения. Демо-плагин должен отображать статус «ОК» .
4. Ждите. Сбор первых данных занимает до 2 минут.

Осмотр

1. Перейдите в раздел «Технологии» и найдите EXAMPLE_SERVICEплитку.
2. Страница «Группа» позволяет анализировать группу и сравнивать эффективность ее участников.
3. Анализируйте различные типы диаграмм на странице устройства.
4. Перейдите к дополнительным сведениям, чтобы найти вкладку «Память».

Настройте расширение

Расширение АктивногоШлюза состоит из двух ключевых файлов: Python и JSON. Файл JSON определяет представление ваших данных на различных страницах Ключ-АСТРОМ. С помощью файла Python вы можете определять дополнительные события и создавать собственные свойства. См. справочник по расширениям АктивногоШлюза и возможности расширений АктивногоШлюза . Попробуйте поэкспериментировать с файлами и посмотреть, как это повлияет на представление данных.

JSON

Файл расширения JSON состоит из следующих четырех основных элементов:

Метаданные

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

{

  "name": "custom.remote.python.example_multi",

  "version": "1.18",

  "productiveMinVersion": "1.000",

  "requiredAgentVersion": "1.000",

  "type": "python",

  "entity": "CUSTOM_DEVICE",

  "metricGroup": "tech.Example_Service",

  "technologies": ["EXAMPLE_SERVICE"],

  "source": {

    "package": "demo_activegate_plugin_multi",

    "className": "RemoteExamplePlugin",

    "install_requires": ["requests>=2.6.0"]

  }

}

Имя расширения АктивногоШлюза должно следовать ^ custom.remote.python (\.[a-zA-Z0-9_]+)+$за регулярным выражением. Например, custom.remote.python.demo. Имя каждого расширения должно быть уникальным.

Свойства technologiesи faviconопределяют, как ваша технология будет представлена ​​на странице «Обзор технологии» . Чтобы данные вашего расширения отображались на плитке существующей технологии, укажите соответствующее имя технологии. Вы можете найти текущие названия технологий в справочнике JSON расширений АктивногоШлюза или найти их в пользовательском интерфейсе как Main technologyсвойство процесса.

Имя пакета и класс, которые должны быть импортированы и выполнены АктивнымШлюзом , соответствуют имени файла Python, содержащего код, и имени определенного в нем класса.

Метрики

Раздел показателей описывает данные, собранные расширением. В этом разделе представлены две метрики, которые отражают как то, что обслуживает наше демонстрационное приложение, так и то, что собирает код Python.

Конфигурационный интерфейс

Разделы ConfigUI и свойств определяют элементы пользовательского интерфейса, используемые для настройки расширения .

Пользовательский интерфейс

Эта часть файла JSON определяет способ отображения показателей. Раздел « Ключевые метрики» позволяет выбрать наиболее важные метрики и представить их в инфографике и на странице группы. Диаграммы вы найдете на вкладке «Дополнительная информация».

Python

Код Python хранится в demo_activegate_plugin_multi.pyфайле.

from ruxit.api.base_plugin import RemoteBasePlugin

from ruxit.api.data import PluginProperty

import math

import logging

from enum import Enum

logger = logging.getLogger(__name__)

class RemoteExamplePlugin(RemoteBasePlugin):

    class State(Enum):

        DOWNTIME = 0

        MAINTENANCE = 1

        WORKING = 2

    def initialize(self, **kwargs):

        self.url = self.config.get("url", "http://127.0.0.1:8976")

        self.user = self.config.get("auth_user", "admin")

        self.password = self.config.get("auth_password", "admin")

        self.alert_interval = self.config.get("alert_interval", 10)

        self.event_interval = self.config.get("event_interval", 3)

        self.relative_interval = self.config.get("relative_interval", 60)

        self.state_interval = self.config.get("state_interval", 60)

        self.alert_iterations = 0

        self.event_iterations = 0

        self.relative_iterations = 0

        self.absolute_iterations = 0

        self.state_iterations = 0

        self.current_entries = 1

        self.archived_entries = 0

    def query(self, **kwargs):

        group_name = self.get_group_name()

        topology_group = self.topology_builder.create_group(group_name, group_name)

        topology_group.per_second("service.querries_per_second", self.get_num_querries())

        topology_group.report_property(key="group_property", value="group_property_value")

        devices = self.get_device_names()

        port = 80

        for device_name in devices:

            topology_device = topology_group.create_device(device_name, device_name)

            topology_device.state_metric("service.state_5", self.get_state_metric())

            topology_device.absolute("databases.total_num_entities", self.get_device_entries())

            table_size = 100

            topology_device.relative("databases.replicated_entries", self.get_archived_entries())

            for table in self.get_tables_for_device(device_name):

                topology_device.absolute("databases.table_size", table_size, {"table_name": table})

                table_size = table_size + 100

            if self.should_create_event():

                topology_device.report_custom_info_event("Custom event!")

                topology_device.report_performance_event("Performance problem description", "Performance problem", {})

            topology_device.report_property(key="device_property", value="device_property_value")

            topology_device.add_endpoint("127.0.0.1", port)

            port += 1

    def get_group_name(self):

        return "ExampleGroup"

    def get_state_metric(self):

        if self.state_iterations >= self.state_interval * 3:

            self.state_iterations = 0

        state = RemoteExamplePlugin.State(int(self.state_iterations / self.state_interval))

        self.state_iterations = self.state_iterations + 1

        return state.name

    def get_num_querries(self):

        self.alert_iterations = self.alert_iterations + 1

        if self.alert_iterations > self.alert_interval:

            if self.alert_iterations > self.alert_interval + 3:

                self.alert_iterations = 0

            return 1

        return 7

    def get_device_names(self):

        return ["DeviceOne", "DeviceTwo"]

    def get_tables_for_device(self, device):

        if device == "DeviceOne":

            return ["d1_t1", "d1_t2", "d1_t3", "d2_t4"]

        return ["d2_t1", "d2_t2", "d2_t3", "d2_t4", "d2_t5", "d2_t6"]

    def get_device_entries(self):

        if self.absolute_iterations == 360:

            self.absolute_iterations = 0

        self.absolute_iterations = self.absolute_iterations + 1

        return self.current_entries + math.sin(math.radians(self.absolute_iterations))

    def get_archived_entries(self):

        self.relative_iterations = self.relative_iterations + 1

        if self.relative_iterations > self.relative_interval:

            self.relative_iterations = 0

            self.archived_entries = self.archived_entries + 1

        return self.archived_entries

    def should_create_event(self):

        self.event_iterations = self.event_iterations + 1

        if self.event_iterations > self.event_interval:

            self.event_iterations = 0

            return True

        return False

Файл определяет RemoteExamplePluginкласс, который, в свою очередь, определяет один запрос метода. При запуске вашего расширения этот метод вызывается каждую минуту для сбора и отправки данных и метрик топологии на сервер Ключ-АСТРОМ.

Демо-приложение возвращает ответ JSON, как показано в примере ниже.

[

  {

    "nodes": [

      {

        "ip": "192.168.0.1",

        "stats": {

          "stats_counter": [6, 10, 13],

          "random": 194,

          "state": "WARNING",

          "counter": 4,

          "version": "1.001"

        },

        "name": "My Node 01"

      },

      {

        "ip": "127.0.0.1",

        "stats": {

          "stats_counter": [7, 10, 11],

          "random": 194,

          "state": "WARNING",

          "counter": 4,

          "version": "1.001"

        },

        "name": "My Node 02"

      }

    ],

    "name": "My Group 01"

  }

]

Метод запроса плагина анализирует ответ, находит группы и устройства и соответствующим образом назначает метрики. Расширение автоматически обнаруживает и отслеживает новые группы и устройства.

Следующие шаги

Это только начало. Ознакомьтесь с другими примерами расширений, поставляемыми вместе с SDK, изучите инструкции и узнайте о других вариантах развертывания .