Перейти к основному содержимому

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

Основная информация

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

  • /api/public/cl/v1/stream-data - для приема логов (событийной информации)

  • /api/public/mcs/v1/metrics-collector - для приема метрик в различных форматах (prometheus, zabbix, text)

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

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

ПараметрТипТребуетсяОписание
streamKeystringдаКлюч потока данных, в который требуется отправить данные

Параметр streamKey требуется, если ключ не указан как параметр HTTP заголовка.

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

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

Прием логов в 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), то в него записывается название самой метки.