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

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

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

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

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

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

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

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

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

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

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

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