Версия: 8.1

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

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

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

Справка

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

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

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

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

системном Агенте - представлен в виде внутреннего микросервиса
внешнем Агенте (руководство по подключению внешнего Агента)

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

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

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

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

Создать Поток данных
Добавить Задание на вкладке Конфигурация Потока данных
Разработать сценарий Задания, которое будет исполнятся на подключенном Агенте

Примеры сценариев заданий
Сохранить и запустить Поток данных

Синтаксис заданий "Потоков данных" 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	строка	-	-	Оболочка ОС. Может быть указан либо путь к исполняемому файлу, либо одно из предзаданных значений.

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

Значение	Заменяющая команда
cmd	`cmd.exe /C <command>`
bash	`bash -c "<command>"`
powershell	`powershell.exe -Command <command>`
pwsh	`pwsh -Command <command>`
sh	`sh -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, то сначала выполнится плагин, а потом последовательно выполнится консольная команда.

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

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

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

JSONPath

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

Liquid

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-ключ текущего потока данных.

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

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

Приведенный пример задания выполняет на Агенте команду 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

Пример запуска функциональных тестов 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

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

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

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

jobs​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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