Интеграция со сторонними системами, извлекающими метрики

1. Описание межкомпонентного и интеграционного взаимодействия#

1.1. Схема компонентов и интеграций#

На данной схеме отражены компоненты Визиона и интеграции с внешними сервисами. Красные стрелки отвечают за внешние связи, чёрные — за внутренние.

Экспортеры взаимодействуют с внешними сервисами, vision_core — с системами идентификации, alertmanager и snmp_notifier — с системами рассылок.

1.2. Перечень компонентов#

Компонент	Местоположение	Сервис	Порты по умолчанию	Описание
`vision_core`	Сервер	`vision_core`	8088	Сервер Визиона
`vision_taskdaemon`	Сервер	`vision_taskdaemon`	-	Сервис выполнения задач из служебной БД
`vision_alertcollector`	Сервер	`vision_alertcollector`	10111	Сервис сбора оповещений в служебную БД
`nginx`	Сервер	`nginx`	80, 443	Веб-сервер
`postgresql`	Сервер	`postgresql`	5432	Служебная БД
`victoriametrics_st`	Сервер	`victoriametrics_st`	8428	БД временных рядов
`grafana`	Сервер	`grafana`	3000	Средство визуализации
`alertmanager`	Сервер	`alertmanager`	9093	Средство отправки оповещений
`vmalert_st`	Сервер	`vmalert_st`	8880	Сервис проверки срабатывания триггеров
`snmp_notifier`	Сервер	`snmp_notifier`	9464	Средство отправки оповещений по SNMP
`vmagent_proxy`	Прокси	`vision_vmagent_proxy`	8430	Сервис приёма метрик ПАКа и отправки их в БДВР
`vmagent_agent`	Агент	`vision_vmagent_agent`	7529	Сервис сбора метрик и отправки их в Прокси
`postgres_exporter_agent`	Агент	`vision_postgres_exporter_agent`	9187	Экспортер
`postgres_exporter_multi`	Агент	`vision_postgres_exporter_multi`	9188	Экспортер
`supv_exporter`	Агент	`vision_supv_exporter`	9179	Экспортер
`vision_exporter`	Агент	`vision_exporter`	7531	Экспортер
`utlz_exporter`	Агент	`vision_utlz_exporter`	9092	Экспортер
`utlz_exporter_v0`	Агент	`vision_utlz_exporter_v0`	17070	Экспортер
`one_exporter`	Агент	`vision_one_exporter`	9621	Экспортер
`node_exporter`	Агент	`vision_node_exporter`	9101	Экспортер
`nginx_exporter`	Агент	`vision_nginx_exporter`	9113	Экспортер
`sql_exporter`	Агент	`vision_sql_exporter`	9399	Экспортер
`snmp_exporter`	Агент	`vision_snmp_exporter`	9116	Экспортер
`ha_cluster_exporter`	Агент	`vision_ha_cluster_exporter`	9664	Экспортер
`ipmi_exporter`	Агент	`vision_ipmi_exporter`	9290	Экспортер
`plagent`	На всех узлах	`plagent`	7550, 7551	Агент управления конфигурацией

1.3. Описание внешнего API#

Действие	Авторизация	Метод	Путь	Описание
Версия	-	GET	https://<ip-Сервер>/vision/api/v1/version	`json { "status": "success", "data": { "vision_version": "1.4-287", "components": {} }, "pagination": null, "message": null, "error": null }`
Создание токена	Визион (writer)	POST	`https://<ip-Сервер>/vision/api/v1/auth/token/	`json { "status": "success", "data": { "jti": "03a4e822-4751-4b90-beb3-96d592944d4f", "name": "test", "created_at": "2024-06-04T11:15:05.809707+03:00", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTcxNzQ4ODkwNSwiaXNzIjoiVmlzaW9uIiwianRpIjoiMDNhNGU4MjItNDc1MS00YjkwLWJlYjMtOTZkNTkyOTQ0ZDRmIn0.K4chZIUqxxkFGIZXEsconxe2t1k3KequW27BPkYCXO4" }, "pagination": null, "message": null, "error": null }`
Просмотр списка токенов	Визион (reader writer)	GET	https://<ip-Сервер>/vision/api/v1/auth/token/	`json { "status": "success", "data": [ { "jti": "03a4e822-4751-4b90-beb3-96d592944d4f", "name": "test", "created_at": "2024-06-04T11:15:05.809707+03:00" } ], "pagination": null, "message": null, "error": null }`
Перевыпуск токена			Выполняется путем отзыва старого токена и создание нового с тем же именем
Отзыв токена	Визион (writer)	POST	https://<ip-Сервер>/vision/api/v1/auth/token/revoke	`json { "status": "success", "data": { "jti": "03a4e822-4751-4b90-beb3-96d592944d4f", "name": "test", "created_at": "2024-06-04T11:15:05.809707+03:00" }, "pagination": null, "message": null, "error": null }`
Работа с БДВР	Токен	GET	https://<ip-Сервер>/vision/api/v1/tsdb/*	Предоставляет доступ к API VictoriaMetrics для получения метрик. Доступны следующие запросы: `/query, /query_range, /labels, /labels/{label_name}/values, /status/tsdb, /series, /federate`
Получение дерева объектов	Токен	GET	https://<ip-Сервер>/vision/api/v1/object/	json { "status": "success", "data": [ { "id": "mbdp", "parent_id": null, "type": "PAK", "attrs": { "type": "Базовый", "description": "" }, "edited_at": "2024-07-30T13:25:43.773216+03:00", "created_at": "2024-07-30T13:24:52.186385+03:00", "links": [], "count": { "MODULE": 1, "NODE": 1, "VM": 1 }, "children": [ { "id": "mbdp_mod", "parent_id": "mbdp", "type": "MODULE", "attrs": { "type": "Базовый модуль" }, "edited_at": "2024-07-30T13:25:43.845822+03:00", "created_at": "2024-07-30T13:24:52.265375+03:00", "links": [], "count": { "NODE": 1, "VM": 1 }, "children": [ { "id": "mbdp_host", "parent_id": "mbdp_mod", "type": "NODE", "attrs": { "type": "Базовый сервер", "address": "172.29.225.160", "address_bmc": "127.0.0.4" }, "edited_at": "2024-07-30T13:25:43.853346+03:00", "created_at": "2024-07-30T13:24:52.357564+03:00", "links": [], "count": { "VM": 1 }, "children": [ { "id": "mbdp_vm", "parent_id": "mbdp_host", "type": "VM", "attrs": { "address": "192.168.190.143" }, "edited_at": "2024-07-30T13:25:43.865414+03:00", "created_at": "2024-07-30T13:24:52.425310+03:00", "links": [], "count": {}, "children": [], "foliage": {} } ], "foliage": {} } ], "foliage": {} } ], "foliage": { "pak": "https://127.0.0.1:443/?view=hss&id=mbdp", "server": "https://127.0.0.1:443/?view=netconnections&id=mbdp", "comm": "https://127.0.0.1:443/?view=netconnections&id=mbdp" } } ] }

1.3.1. Авторизация через токен#

Токен используется в заголовке Authorization в следующем виде - Authorization: Bearer {token}

2. Список роутов vision_core с ролями и токенами#

Список всех роутов HTTP API Визион.Сервера с правами доступа

3. Точка интеграции с Zabbix#

3.1. Получение списка метрик#

Получить текущий список активных метрик можно с помощь эндпоинта:

https://<VISION>/vision/victoriametrics/prometheus/api/v1/label/__name__/values

<VISION> - адрес Сервера Визиона.

Для получения доступа к эндпоинту необходимо пройти BasicAuth аутентификацию. Учетная запись по умолчанию - vision, пароль - skala-r.

3.2. Извлечение значений#

Существует несколько способов извлечения метрик и их текущих значений из Визиона в Zabbix:

3.2.1. С помощью федерации#

Эндпоинт:

https://<VISION>/vision/victoriametrics/federate?match[]=<MATCH>

<MATCH> - выражение для фильтрации метрик в виде PromQL, например: - {__name__=~".*"} - все метрики (использовать не рекомендуется, оказывается большая нагрузка на мониторинг) - utlz_mem_used - все метрики с именем utlz_mem_used - {_pak_id=“mbd2”} - все метрики ПАК mbd2

Пример:

https://192.168.190.188/vision/victoriametrics/federate?match[]=utlz_mem_used

Метрики отдаются в текстовом формате в виде строк формата:

ИМЯ_МЕТРИКИ{ИМЯ_МЕТКИ_1="ЗНАЧЕНИЕ_МЕТКИ_1", ...} ЗНАЧЕНИЕ_МЕТРИКИ ОТМЕТКА_ВРЕМЕНИ

Пример: utlz_mem_used{job=“utlz_exporter”,instance=“127.0.0.1:9092”,_module_id=“db-module”,_node_id=“mbd8-adb-segment1”,_pak_id=“pl-mbd8”,_target_id=“13”,_target_type=“NODE”} 1119604000 1719840495170 utlz_mem_used{job=“utlz_exporter”,instance=“127.0.0.1:9092”,_module_id=“db-mbdp-module”,_node_id=“pl-mbd2-0”,_pak_id=“pl-mbd2”,_target_id=“37”,_target_type=“NODE”} 144613640000 1719840485772…

3.2.2. С помощью запроса#

Эндпоинт:

https://<VISION>/vision/victoriametrics/api/v1/query?query=<QUERY>

<QUERY> - запрос на получение метрики в виде PromQL (аналогично выражению для <MATCH>).

Пример:

https://192.168.190.188/vision/victoriametrics/api/v1/query?query=utlz_mem_used

Метрики отдаются в формате JSON вида:

{
  "status": "success",
  "data": {
    ...
    "result": [
      {
        "metric": {
          "__name__": "ИМЯ_МЕТРИКИ",
          "ИМЯ_МЕТКИ_1": "ЗНАЧЕНИЕ_МЕТКИ_1",
          ...
        },
        "value": [
          ЗНАЧЕНИЕ_МЕТРИКИ,
          "ОТМЕТКА_ВРЕМЕНИ"
        ]
      },
      ...
    ]
  },
  ...
}

Пример:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "utlz_mem_used",
          "_module_id": "db-mbdp-module",
          "_node_id": "pl-mbd2-0",
          "_pak_id": "pl-mbd2",
          "_target_id": "37",
          "_target_type": "NODE",
          "instance": "127.0.0.1:9092",
          "job": "utlz_exporter"
        },
        "value": [
          1719840527,
          "144613640000"
        ]
      },
      {
        "metric": {
          "__name__": "utlz_mem_used",
          "_module_id": "db-mbdp-module",
          "_node_id": "pl-mbd2-1",
          "_pak_id": "pl-mbd2",
          "_target_id": "39",
          "_target_type": "NODE",
          "instance": "127.0.0.1:9092",
          "job": "utlz_exporter"
        },
        "value": [
          1719840527,
          "144515996000"
        ]
      },
	  ...
    ]
  },
  "stats": {
    "seriesFetched": "13"
  }
}

3.3.3. Метки#

У метрик присутствуют следующие служебные метки:

_pak_id - идентификатор ПАК
_target_id - идентификатор объекта (задачи) мониторинга
_target_type - тип объекта (задачи) мониторинга. В зависимости от типа (NODE - узел, VM - виртуальная машина, COMM - коммутатор, SERVICE - сервис) и особенностей объекта (задачи) мониторинга метрика получает дополнительные служебные метки:
- _module_id - идентификатор модуля ПАК
- _node_id - идентификатор узла ПАК
- _vm_id - идентификатор служебной виртуальной машины ПАК
- _comm_id - идентификатор коммутатора ПАК

Также могут присутствовать и иные метки, которые позволяют фильтровать информацию или отвечают за хранение данных.

4. VictoriaMetrics/Prometheus API для работы с данными#

4.1 VictoriaMetrics#

Документация

Примеры

VictoriaMetrics поддерживает следующие запросы к Prometheus API:

/api/v1/query
/api/v1/query_range
/api/v1/series
/api/v1/labels
/api/v1/label/…/values
/api/v1/status/tsdb
/api/v1/targets
/federate

4.2. Prometheus#

Документация

4.3. Общее описание#

HTTP API доступен по роуту /api/v1 Формат ответа API — JSON. Каждый успешный запрос API возвращает 2xx код состояния.

Общий вид ответа JSON:

{
  "status": "success" | "error",
  "data": <data>,

  // Только для статуса "error"
  "errorType": "<string>",
  "error": "<string>",

  // Только если были предупреждения
  "warnings": ["<string>"]
}

Описание заполнителей в нижеприведенных параметрах URL-запросов:

<rfc3339 | unix_timestamp>: входные временные метки могут быть предоставлены либо в формате RFC3339 или в виде временной метки Unix, в секундах с необязательными десятичными разрядами для точности до доли секунды. Выход метки времени всегда представлены как метки времени Unix в секундах.
<series_selector>: временной ряд Прометея селекторам на подобии http_requests_total или http_requests_total{method=~"(GET|POST)"}и должны быть закодированы в URL.
<duration>: период времени. Например, 5m - 5 минут.
<bool>: логические значения (строки true и false).

4.4. Запросы#

GET /api/v1/query

Параметры URL-запроса:

query=<string>: строка выражения
time=<rfc3339 | unix_timestamp>: Отметка времени оценки. Необязательный.
timeout=<duration>: Время ожидания оценки. Необязательный. По умолчанию и ограничивается значением -query.timeout флаг.

GET /api/v1/query_range

Параметры URL-запроса:

query=<string>: строка запроса выражения Prometheus.
start=<rfc3339 | unix_timestamp>: Отметка времени начала включительно.
end=<rfc3339 | unix_timestamp>: Отметка времени окончания включительно.
step=<duration | float>: Ширина шага разрешения запроса в durationформат или число с плавающей запятой в секундах.
timeout=<duration>: Время ожидания оценки. Необязательный. По умолчанию и ограничивается значением -query.timeoutфлаг.

GET /api/v1/series

Параметры URL-запроса:

match[]=<series_selector>: Аргумент селектора повторяющейся серии, который выбирает серия, чтобы вернуться. Хотя бы один match[]аргумент должен быть предоставлен.
start=<rfc3339 | unix_timestamp>: Отметка времени начала.
end=<rfc3339 | unix_timestamp>: метка времени окончания.

GET /api/v1/labels

Параметры URL-запроса:

start=<rfc3339 | unix_timestamp>: Отметка времени начала. Необязательный.
end=<rfc3339 | unix_timestamp>: метка времени окончания. Необязательный.
match[]=<series_selector>: Аргумент селектора повторяющейся серии, который выбирает серия, из которой можно прочитать названия этикеток. Необязательный.

GET /api/v1/label/<label_name>/values

Параметры URL-запроса:

start=<rfc3339 | unix_timestamp>: Отметка времени начала. Необязательный.
end=<rfc3339 | unix_timestamp>: метка времени окончания. Необязательный.
match[]=<series_selector>: Аргумент селектора повторяющейся серии, который выбирает ряд, из которого считываются значения меток. Необязательный.

GET /api/v1/status/tsdb

GET /api/v1/targets

5. Настройка Визион для аутентификации сторонних сервисов#

Настройка Визиона для аутентификации сторонних сервисов