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

API - Потоки данных

Прием данных

Monq предоставляет пользователю две точки для прослушивания HTTP POST запросов:

Общие параметры для приема логов и метрик

Параметр запросаТипОбязательный параметрЗначение по умолчаниюОписание
streamKeystringда, если не указан заголовок x-smon-stream-keyнетКлюч потока данных, в который требуется отправить данные
Заголовок запросаТипОбязательный заголовокЗначение по умолчаниюОписание
x-smon-stream-keystringда, если не указан параметр streamKeyнетКлюч потока данных, в который требуется отправить данные

Прием событий и логов в Monq

POST /api/public/cl/v1/stream-data

Параметры заголовков запроса для приема логов

ПараметрТипОбязательный параметрЗначение по умолчаниюОписание
Content-TypestringданетОбязательным требованием является указание типа отправляемых данных

Monq способен принять события в следующих форматах:

  • application/json
  • application/x-ndjson
  • text/xml
  • text/plain

Тело запроса

Телом запроса является строка с данными, которые требуется отправить на обработку.

Вы можете указать структурированный тип данных application/json, application/x-ndjson. В этом случае при приеме данных будет проведена валидация. Если формат данных не соответствует типу, событие будет отброшено и будет возвращена ошибка HTTP StatusCode 400 BadRequest.

Для сообщений, имеющих тип application/json, application/x-ndjson имеется возможность задать поле “@timestamp”: “2019-07-25T09:16:39.284622281Z“, в котором будет установлена дата произошедшего события. Если такое поле указано, то дата события в Monq будет использовать значение поля, если не указана другая инструкция в препроцессоре данных.

Если поле отсутствует и не задано в препроцессоре, то значением поля будет дата и время получения события.

Пример запроса CURL

curl --location --request POST 'https://<Monq-FQDN-NAME>/api/public/cl/v1/stream-data?streamKey=<API ключ потока>' \
--header 'Content-Type: application/json' \
--data-raw '{
"@timestamp": "2020-04-29T12:12:56.000000+00:00",
"stream": "stdout",
"docker": {
"container_id": "e988087df502e32cdcb16233ca5974398497061a8d6fed1586ec9336cfd63c2b"
},
"kubernetes": {
"container_name": "nginx-ingress-controller",
"namespace_name": "kube-system",
"pod_name": "nginx-ingress-controller-c95qd",
"container_image": "quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.20.0",
"pod_id": "79ff1d4c-89ea-11ea-b298-fabbba8ed4fb",
"host": "d3-d-node-02",
"labels": {
"app": "nginx-ingress",
"controller-revision-hash": "3781051395",
"pod-template-generation": "16"
},
"master_url": "https://10.16.0.1:443/api",
"namespace_id": "c7f77c99-d6d7-11e8-bd7f-7ee4f896140a",
"namespace_labels": { "certmanager_k8s_io/disable-validation": "true" }
},
"remote": "10.18.0.81",
"realip": "10.18.0.81",
"user": "-",
"method": "GET",
"path": "/api/v1/nodes/d3-d-node-02/proxy/metrics",
"protocol": "HTTP/1.1",
"code": 200,
"size": 8172,
"agent": "Prometheus/2.14.0",
"request_length": 344,
"request_time": 0.064,
"upstream_response_length": 8172,
"upstream_response_time": 0.065,
"upstream_status": 200,
"req_id": "b82905a8aadaca97b7b1662e6d1536f5\n"
}
'

Прием метрик в Monq

Помимо основного способа приема метрик из Prometheus, получать их можно также и из других систем.

В таком случае метрики необходимо предварительно преобразовать в Prometheus-формат. После чего внешнюю систему требуется сконфигурировать на отправку преобразованных метрик в Monq по API.

Прием метрик через Prometheus remote write

POST /api/public/mcs/v1/metrics-collector/prometheus/remote-write

Формат сообщенийОписание
Prometheus ProtobufТочка используется для приема метрик в машинном формате.
Потенциально данная точка может обработать большее количество метрик в секунду,
чем точка в текстовом формате.

Прием метрик в text/plain формате

POST /api/public/mcs/v1/metrics-collector/prometheus/plain

Формат сообщенийОписание
Prometheus Text Based FormatТочка используется для приема метрик в человеко-читаемом текстовом формате.
Формат, который можно использовать - Prometheus Plain, так же как и OpenMetrics Text Format.

Пример запроса для приема метрик в Monq в text-based формате

curl --location --request POST 'https://<Monq-FQDN-NAME>/api/public/mcs/v1/metrics-collector/prometheus/plain' \
--header 'x-smon-stream-key: <API ключ потока>' \
--header 'Content-Type: text/plain' \
--data-raw 'CPU{method="post",code="200"} 125 1666702336924

Коды ответа

КодОписание
200Запрос успешно исполнен
400Данные не прошли валидацию
422Поток данных с ключом {streamKey} не объявлен в системе
422Поток данных с ключом {streamKey} не активен
422Поток данных с ключом {streamKey} ожидает удаления
500Непредвиденная ошибка при обработке запроса на стороне сервера

Прием метрик в формате Newline-delimited JSON export protocol

POST /api/public/mcs/v1/metrics-collector/zabbix/stream-ndjson?streamKey=<streamKey>

Формат сообщенийОписание
Newline-delimited JSON export protocolТочка используется для приема метрик в формате Zabbix
  • Из потока данных обрабатываются только числовые значения метрик (type=3 и type=0)

Формат поступающих в Monq метрик из Zabbix

{
"host": {
"host": "Host B",
"name": "Host B visible"
},
"groups": [
"Group X",
"Group Y",
"Group Z"
],
"item_tags": [
{
"tag": "foo",
"value": "test"
}
],
"itemid": 3,
"name": "Agent availability",
"clock": 1519304285,
"ns": 123456789,
"value": 1,
"type": 3
}

На стороне Monq происходит конвертация данных в привычные нам метрики.

Модель host преобразовывается в набор меток: "host":"Host B" и "hostName":"Host B visible"

Модель groups преобразовывается в метку: "groups":["Group X","Group Y","Group Z"]

Из массива item_tags извлекаются все пары меток и добавляются как отдельные метки. Если поле value пустое (нормальное поведение, согласно документации Zabbix), то в него записывается название самой метки.

Управление конфигурацией потоков данных

Частично обновить поток данных

PATCH /api/public/cl/v1/streams/{streamId}

Параметры запроса

Название параметраТип параметраОбязательный параметрЗначение по умолчаниюОписание параметра
streamIdintegerданетИдентификатор потока данных

Тело запроса

{
"state": "Running"
}

Поля тела запроса

Название поляТип поляОбязательное полеОписание поля
statestringдаRunning - поток запущен
Paused - поток остановлен

Коды ответа

Код ответаОписание
200Поток данных успешно обновлен
400Неверная модель данных в теле запроса
401Не удалось выполнить авторизацию пользователя
403Недостаточно прав для обновления потока
404Поток данных с указанным идентификатором не найден
415Неправильный тип входных данных. Требуется указать тип: application/json
500Непредвиденная ошибка при обработке запроса

Удалить поток данных по идентификатору

DELETE /api/public/cl/v1/streams/{streamId}

Параметры запроса

Название параметраТип параметраОбязательный параметрЗначение по умолчаниюОписание параметра
streamIdintegerданетИдентификатор потока данных

Коды ответа

Код ответаОписание
204Поток данных успешно удален
400Недопустимое значение идентификатора потока данных
401Не удалось выполнить авторизацию пользователя
403Недостаточно прав для удаления потока
404Поток данных с указанным идентификатором не найден
500Непредвиденная ошибка при обработке запроса

Создать поток данных

POST /api/public/cl/v1/streams

Тело запроса

{
"name": "Название потока",
"description": "Описание потока",
"ownerWorkGroup": {
"id": 0
}
}

Поля тела запроса

Название поляТип поляОбязательное полеЗначение по умолчаниюОписание поля
namestringданетНазвание потока
descriptionstringнетnullОписание потока
ownerWorkGroup.idintegerданетИдентификатор рабочей группы владельца потока данных

Коды ответа

Код ответаОписание
201Поток данных успешно создан
400Пустое тело запроса
400Неверная модель данных в теле запроса
400Требуется указать название потока данных
400Требуется указать рабочую группу-владельца потока данных
400Недопустимое значение идентификатора рабочей группы
400Поток данных с названием {name} уже существует
401Не удалось выполнить авторизацию пользователя
403Недостаточно прав для обновления потока
415Неправильный тип входных данных. Требуется указать тип: application/json
500Непредвиденная ошибка при обработке запроса

Импортировать поток данных

POST /api/public/cl/v1/streams/import

Тело запроса

{
"name": "Название потока",
"description": "Описание потока",
"ownerWorkGroup": {
"id": 0
},
"importBase64": "string"
}

Поля тела запроса

Название поляТип поляОбязательный параметрЗначение по умолчаниюОписание поля
namestringданетНазвание потока
descriptionstringнетnullОписание потока
ownerWorkGroup.idintegerданетИдентификатор рабочей группы владельца потока данных
importBase64stringданетСтрока для импорта потока данных в формате base64

Коды ответа

Код ответаОписание
201Поток данных успешно создан
400Пустое тело запроса
400Неверная модель данных в теле запроса
400Требуется указать название потока данных
400Требуется указать рабочую группу-владельца потока данных
400Недопустимое значение идентификатора рабочей группы
400Поток данных с названием {name} уже существует
401Не удалось выполнить авторизацию пользователя
403Недостаточно прав для обновления потока
415Неправильный тип входных данных. Требуется указать тип: application/json
500Непредвиденная ошибка при обработке запроса