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

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

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

Справка

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

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

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

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

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

Шаблонные задания

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

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

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

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

  1. Создать Поток данных с Шаблоном конфигурации Default template.

  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объект настроек отправки артефакта--Настройки отправки данных артефакта.

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

НазваниеТипОбязательноШаблонОписание
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 — идентификатор пользовательского пространства.
  • 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: https://monq.example.com/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-ключ текущего потока данных.

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

Изображение

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

Приведенный пример задания выполняет на Агенте команду 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: https://monq.example.com/api/public/cl/v1/stream-data
headers:
x-smon-stream-key: $.vars.stream.key
media-type: application/json

Пример запуска функциональных тестов 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: https://monq.example.com/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: https://{monq-url}/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: https://{monq-url}/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: https://{monq-url}/api/public/cl/v1/stream-data
headers:
x-smon-stream-key: $.vars.stream.key
media-type: application/json