Версия: 8.3

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

Прием данных

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

/api/public/cl/v1/stream-data - для приема событий и логов (событийной информации)
/api/public/mcs/v1/metrics-collector - для приема метрик в различных форматах (prometheus, zabbix, text)

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

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

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

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

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

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

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

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}

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

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

Тело запроса

{
  "state": "Running"
}

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

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

Коды ответа

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

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

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

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

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

Коды ответа

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

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

POST /api/public/cl/v1/streams

Тело запроса

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

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

Название поля	Тип поля	Обязательное поле	Значение по умолчанию	Описание поля
name	`string`	да	нет	Название потока
description	`string`	нет	`null`	Описание потока
ownerWorkGroup.id	`integer`	да	нет	Идентификатор рабочей группы владельца потока данных

Коды ответа

Код ответа	Описание
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"
}

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

Название поля	Тип поля	Обязательный параметр	Значение по умолчанию	Описание поля
name	`string`	да	нет	Название потока
description	`string`	нет	`null`	Описание потока
ownerWorkGroup.id	`integer`	да	нет	Идентификатор рабочей группы владельца потока данных
importBase64	`string`	да	нет	Строка для импорта потока данных в формате `base64`

Коды ответа

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

Прием данных​

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

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

Тело запроса​

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

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

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

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

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

Коды ответа​

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

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

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

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

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

Тело запроса​

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

Коды ответа​

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

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

Коды ответа​

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

Тело запроса​

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

Коды ответа​

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

Тело запроса​

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

Коды ответа​

Прием данных

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

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

Тело запроса

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

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

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

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

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

Коды ответа

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

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

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

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

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

Тело запроса

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

Коды ответа

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

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

Коды ответа

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

Тело запроса

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

Коды ответа

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

Тело запроса

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

Коды ответа