Перейти к основному содержимому
Версия: 8.4

Задания потоков данных

Для интеграции с внешними Информационными системами, где требуется получение данных по технологии pull, предусмотрены:

Справка

Технология pull (англ. pull technology, pull coding или client pull - сбор чего-либо ) - технология сетевой коммуникации, при которой первоначальный запрос данных производится клиентом, а ответ порождается сервером.

Задание представляет собой сценарий, написанный на языке разметки Yaml.

Результатом выполнения сценария является "артефакт" - далее передаваемый в Поток данных Monq через REST API.

Задания Потоков данных могут выполнятся на:

Руководство пользователя по работе с Заданиями

Пользовательские задания​

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

Для создания интеграции с внешней Информационной системой необходимо:

  1. Создать Поток данных

  2. Добавить Задание на вкладке Конфигурация Потока данных

  3. Разработать сценарий Задания, которое будет исполнятся на подключенном Агенте

    Примеры сценариев заданий

  4. Сохранить и запустить Поток данных

Синтаксис заданий "Потоков данных" monq​

Сценарий — это настраиваемый автоматизированный процесс, состоящий из одного или нескольких заданий (Job).

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

Задания Потоков данных используют синтаксис языка YAML. Редактирование сценария производится в интерфейсе Monq.

jobs​

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

Поля сценария​

НазваниеТипОбязательноШаблонОписание
nameстрока--Название сценария
envпроизвольный словарь-+Глобальные переменные окружения, доступные в любом месте сценария.
settingsобъект настроек--Настройки выполнения сценария.
jobsмассив служебных работ+-Служебные работы сценария, выполняющиеся параллельно.

Поля служебных работ​

НазваниеТипОбязательноШаблонОписание
nameстрока--Название служебной работы
envпроизвольный словарь-+Переменные окружения, доступные в любом месте служебной работы. Значения перетирают значения совпадающих ключей в словаре сценария.
settingsобъект настроек--Настройки выполнения служебной работы.
stepsмассив шагов+-Шаги служебной работы сценария, выполняющиеся последовательно.
storeпроизвольный словарь-+Сохраняемые в глобальном кэше переменные, значения которых передаются в следующий запуск сценария. Значения перетирают значения совпадающих ключей в словарях шагов. Также значения совпадающих ключей перетираются значениями в словарях других служебных работ, выполненных позже.
artifactsмассив артефактов--Сформированные артефакты выполнения служебной работы.

Поля шага служебной работы​

НазваниеТипОбязательноШаблонОписание
nameстрока--Название шага служебной работы.
envпроизвольный словарь-+Переменные окружения, доступные в любом месте шага служебной работы. Значения перетирают значения совпадающих ключей в словарях сценария и служебной работы.
settingsобъект настроек--Настройки выполнения шага служебной работы.
runстрока++Консольная команда для исполнения на агенте.
pluginстрока++Команда агентского плагина для исполнения на агенте.
withпроизвольный словарь-+Переменные исполняемой команды.
with-securedпроизвольный словарь-+Защищённые переменные исполняемой команды, значения которых скрываются в логах.
outputsпроизвольный словарь-+Возвращаемые значения.
storeпроизвольный словарь-+Сохраняемые в глобальном кэше переменные, значения которых передаются в следующий запуск сценария.

Поля настроек​

НазваниеТипОбязательноШаблонОписание
shellстрока--Оболочка ОС. Может быть указан либо путь к исполняемому файлу, либо одно из предзаданных значений.

Предзаданные значения оболочек​

ЗначениеЗаменяющая команда
cmdcmd.exe /C <command>
bashbash -c "<command>"
powershellpowershell.exe -Command <command>
pwshpwsh -Command <command>
shsh -c '<command>'

Для различных семейств ОС используются значения по умолчанию:

  • Windows — cmd
  • Unix — bash

В остальных случаях нужно обязательно явно указать желаемую оболочку.

Поля артефакта​

НазваниеТипОбязательноШаблонОписание
nameстрока--Название артефакта.
pathsмассив строк-+Пути к файлам, которые будут помещены в один архив.
filesмассив строк-+Список путей к файлам, которые будут переданы отдельно.
dataпроизвольный объект-+Данные артефакта.
send-toобъект настроек отправки артефакта--Настройки отправки данных артефакта.

Данные артефакта​

В поле data пользователи, при написании сценария могут сформировать модель события которое будет отправлено в коллектор Monq.

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

Например, если у нас имеется следующее событие, хранящееся в переменной outputs.test.responseData:

{
    "string": "text",
    "number": 123,
    "arrayString": ["test1", "test2", "123"],
    "arrayNumber": [1, 2, 3],
    "boolean": false,
    "null": null,
    "object": {
        "string": "text",
        "number": 123,
        "array": ["test1", "test2", "123"],
        "boolean": false,
        "null": null
    }
}

  • string - чтобы отправить значение поля с типом string, его нужно обязательно заключать в кавычки, иначе данные будут конвертированы в невалидный json и соответственно не будут отправлены. Пример использования:

    artifacts:
      - data: >
          {
            "string": " {{ outputs.test.responseData.string }} "
          }

  • arrayString, object, number, boolean - чтобы отправить значение поля с одним из перечисленных типов, нужно воспользоваться следующей конфигурацией (без использования кавычек):

    artifacts:
      - data: >
          {
            "object":  {{ outputs.test.responseData.object }}
          }

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

    artifacts:
      - data: >
          {
            "null":  {% if outputs.test.responseData.null == nil %} null {% endif %}
          }

Поля настроек отправки артефакта​

НазваниеТипОбязательноШаблонОписание
monqобъект настроек отправки в monq--Настройки отправки в monq.
apiобъект настроек API запроса--Настройки отправки через API запрос.

Поля настроек отправки в monq​

НазваниеТипОбязательноШаблонОписание
keysмассив строк--Специальные системные ключи.

Поля настроек API запроса​

НазваниеТипОбязательноШаблонОписание
methodстрока-+Метод запроса. По умолчанию POST.
uriстрока-+URI запроса.
headersпроизвольный словарь-+Заголовки запроса.
query-paramsпроизвольный словарь-+Параметры запроса.
media-typeстрока-+Тип тела запроса. По умолчанию application/json.

Минимальная структура сценария​

Для каждого YAML сценария должна быть определена минимальная структура в одной из следующих вариаций:

jobs:
  - steps:
      - run: echo Hello!
jobs:
  - steps:
      - plugin: pluginName
jobs:
  - steps:
      - plugin: pluginName
        run: echo Hello!

Если указаны и команда плагина plugin, и консольная команда run, то сначала выполнится плагин, а потом последовательно выполнится консольная команда.

Шаблонизация​

В некоторых полях сценария поддерживается указание шаблонов. В шаблонах можно обращаться к различным группам переменных.

Доступно несколько шаблонизаторов:

jobs:
  - steps:
      - run: date /c
        store:
          currentDate: $._outputs.shell
jobs:
  - steps:
      - run: date /c
        store:
          currentDate: {{ _outputs.shell }}

Группы переменных​

  • env — переменные окружения. Имеют область видимости в зависимости от места, в котором определены.

  • vars — переменные агентского задания. В неявном виде может передаваться информация о владельце задания:

    • stream — поток данных:
    {
      "id": 0,
      "name": "",
      "key": "00000000-0000-0000-0000-000000000000",
      "params": {
        "key": "value"
      }
    }

  • storage — переменные глобального кэша.

  • Системные переменные:

    • userspaceId — идентификатор пользовательского пространства.
    • baseUri — URL адрес текущего пространства Monq (например, https://monq.example.com/).

  • outputs — возвращаемые переменные служебной работы. Имеют область видимости в соответствующей служебной работе.

  • _outputs — возвращаемые переменные шага служебной работы. Имеют область видимости на соответствующем шаге служебной работы. По завершении шага переменные совмещаются с переменными соответствующей служебной работы. Содержат предзаданные переменные:

    • shell — вывод успешно выполненной консольной команды.

Примеры сценариев​

Ниже приведены примеры сценариев для использования в Заданиях потоков данных.

Пример работы с API​

Пример сценария Задания агента для выполнения запроса к "fake API" jsonplaceholder.typicode.com.

---
jobs:
  - steps:
      - run: curl -s https://jsonplaceholder.typicode.com/todos/11
        outputs:
          out_json: $._outputs.shell
    artifacts:
      - data: '{{ outputs.out_json }}'
        send-to:
          api:
            uri: "{{ baseUri }}api/public/cl/v1/stream-data"
            headers:
              x-smon-stream-key: $.vars.stream.key
            media-type: application/json

В данном сценарии представлен один шаг выполнения - run.

При помощи run на внешнем агенте выполняется запуск утилиты curl с соответствующими параметрами.

Результат выполнения команды STDOUT сохраняется как артефакт в переменную out_json из специальной группы переменных _outputs.

Записанные данные артефакта в переменной outputs.out_json, при помощи инструкции send-to, передаются в текущий поток данных, где:

  • uri - URL публичного API потока данных.
  • $.vars.stream.key - API-ключ текущего потока данных.

После успешного выполнения задания в Событиях появится следующая запись:

Изображение

Пример сбора информации с системы в формате json​

Приведенный пример задания выполняет на Агенте команду kubectl get ingresses -n kube-system kubernetes-dashboard -o json и передает результат выполнения в JSON объекте source.value в Monq.

---
jobs:
  - steps:
      - run: kubectl get ingresses -n kube-system kubernetes-dashboard -o json
        outputs:
          data: $._outputs.shell
    artifacts:
      - data: |
        { 
          "value": {{ outputs.data }}
        }
        send-to:
          api:
            uri: "{{ baseUri }}api/public/cl/v1/stream-data"
            headers:
              x-smon-stream-key: $.vars.stream.key
            media-type: application/json

Пример сбора информации с системы в формате text/plain​

Приведенный пример задания выполняет на Агенте команду ls -la / и передает результат выполнения в Monq.

jobs:
  - steps:
      - run: ls -la /
        outputs:
          out_json: $._outputs.shell
    artifacts:
      - data: '{ "value": "{{ outputs.out_json }}" }'
        send-to:
          api:
            uri: "{{ baseUri }}api/public/cl/v1/stream-data"
            headers:
              x-smon-stream-key: $.vars.stream.key
            media-type: text/plain

Пример запуска функциональных тестов pytest​

Приведенный пример запускает Python Framework pytest для проведения функционального тестирования и отправки результатов в Autotests (ex. TestForge).

В данном примере отправка файла allure-result.zip в API - Autotests (ex. TestForge) выполняется средствами Python

---
jobs:
  - steps:
      - run: rm -rf ${WORKSPACE}/allure-results/* && /opt/venv/bin/py.test -v /opt/tests/demo/docs.monq/test_docs.py --alluredir ${WORKSPACE}/allure-results
        env:
          X_FMonq_PROJECT_KEY: 97911b15-d756-4376-802d-4ae54ab29354
          X_SMON_STREAM_KEY: 5ba11e94-2152-4428-b9fb-56988090cd71
          Monq_URL: https://monq.example.com
          WORKSPACE: /opt/workspace
        outputs:
          data: $._outputs.shell
    artifacts:
      - data: '{ "value": "{{ outputs.data }}" }'
        send-to:
          api:
            uri: "{{ baseUri }}api/public/cl/v1/stream-data"
            headers:
              x-smon-stream-key: $.vars.stream.key
            media-type: application/json

Пример получения проблем из Dynatrace​

Данный сценарий запрашивает проблемы из API Dynatrace и отправляет в Monq.

---
jobs:
  - steps:
      - run: 'curl -s https://{dynatrace-url}/api/v2/problems --header \"Authorization: Api-Token {token}\"'
        outputs:
          out_json: "$._outputs.shell"
    artifacts:
       - data: "{{ outputs.out_json }}"
         send-to:
            api:
              uri: "{{ baseUri }}api/public/cl/v1/stream-data"
              headers:
                x-smon-stream-key: $.vars.stream.key
              media-type: application/json

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

Изображение

Пример выполнения запроса к базе данных PostgreSQL​

---
jobs:
  - steps:
      - run: 'PGPASSWORD=password psql -h localhost -U zabbix -d zabbix -c \"select json_agg(users) from users;\" -qtAX'
        outputs:
          out_json: "$._outputs.shell"
    artifacts:
       - data: "{{ outputs.out_json }}"
         send-to:
            api:
              uri: "{{ baseUri }}api/public/cl/v1/stream-data"
              headers:
                x-smon-stream-key: $.vars.stream.key
              media-type: application/json

Пример выполнения запроса к базе данных MySQL​

---
jobs:
  - steps:
      - run: 'mysql -uroot -ppassword mysql -e \"select JSON_ARRAYAGG(JSON_OBJECT(\"name\", User, \"passwd\", Password)) from user;\" -s -N'
        outputs:
          out_json: "$._outputs.shell"
    artifacts:
       - data: "{{ outputs.out_json }}"
         send-to:
            api:
              uri: "{{ baseUri }}api/public/cl/v1/stream-data"
              headers:
                x-smon-stream-key: $.vars.stream.key
              media-type: application/json

Пример выполнения запроса информации о подах кластера Kubernetes​

---
jobs:
- steps:
  - run: kubectl get pod -n sock-shop -o json
    outputs:
      data: $._outputs.shell
  artifacts:
  - data: "{{ outputs.data }}"
    send-to:
      api:
        uri: "{{ baseUri }}api/public/cl/v1/stream-data"
        headers:
          x-smon-stream-key: $.vars.stream.key
        media-type: application/json