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