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

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

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

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

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

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

Компонент	Местоположение	Сервис	Порты по умолчанию	Описание
`vision_core`	Сервер	`vision_core`	8088	Сервер Визиона
`vision_taskdaemon`	Сервер	`vision_taskdaemon`	-	Сервис выполнения задач из служебной БД
`vision_alertcollector`	Сервер	`vision_alertcollector`	10111	Сервис сбора оповещений в служебную БД
`vision_iamsyncer`	Сервер	`vision_iamsyncer`	17080	Сервис для синхронизации данных о ролях и пользователях между IAM и vision_core
`nginx`	Сервер	`nginx`	80, 443	Веб-сервер
`postgresql`	Сервер	`postgresql`	5432	Служебная БД
`victoriametrics_st`	Сервер	`victoriametrics_st`	8428	БД временных рядов
`victorialogs`	Сервер	`victorialogs`	9428, 29514	Хранилише логов
`grafana`	Сервер	`grafana`	3000	Средство визуализации
`alertmanager`	Сервер	`alertmanager`	9093	Средство отправки оповещений
`vmalert_st`	Сервер	`vmalert_st`	8880	Сервис проверки срабатывания триггеров
`vmalert_vl`	Сервер	`vmalert_vl`	8881	Сервис оценки выражений для создания оповещений или новых временных рядов на основе данных victorialogs
`snmp_notifier`	Сервер	`snmp_notifier`	9464	Средство отправки оповещений по SNMP
`vision_utilizer`	Сервер	`vision_utilizer`	17099	Сервис перерасчета метрик утилизации
`vision_backup`	Сервер	`vision_backup`	17050	Сервис резервного копирования конфигурации Визиона
`vmagent_proxy`	Прокси	`vision_vmagent_proxy`	8430	Сервис приёма метрик ПАК и отправки их в БДВР
`vlagent_proxy`	Прокси	`vision_vlagent_proxy`	29511	Сервис приёма логов ПАК и отправки их в хранилище логов
`vision_logwatcher`	Прокси	`vision_logwatcher`	17078	Сервис отслеживания и распаковки сжатых логов
`vmagent_agent`	Агент	`vision_vmagent_agent`	8429	Сервис сбора метрик и отправки их в Прокси
`vlagent_agent`	Агент	`vision_vlagent_agent`	29510	Сервис приема логов и отправки их в Прокси
`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	Экспортер
`clickhouse_sql_exporter`	Агент	`vision_clickhouse_sql_exporter`	9397	Экспортер
`greenplum_sql_exporter`	Агент	`vision_greenplum_sql_exporter`	9398	Экспортер
`snmp_exporter`	Агент	`vision_snmp_exporter`	9116	Экспортер
`keepalived_snmp_exporter`	Агент	`vision_keepalived_snmp_exporter`	17070	Экспортер
`ha_cluster_exporter`	Агент	`vision_ha_cluster_exporter`	9664	Экспортер
`ipmi_exporter`	Агент	`vision_ipmi_exporter`	9290	Экспортер
`blackbox_exporter`	Агент	`vision_blackbox_exporter`	9115	Экспортер
`graphite_exporter`	Агент	`vision_graphite_exporter`	9108	Экспортер
`kafka_exporter`	Агент	`vision_kafka_exporter`	9308	Экспортер
`process_exporter`	Агент	`vision_process_exporter`	9120	Экспортер
`systemd_exporter`	Агент	`vision_systemd_exporter`	9110	Экспортер
`kubernetes_exporter`	Агент	`vision_kubernetes_exporter`	9130	Экспортер
`r_virtualization_exporter`	Агент	`vision_r_virtualization_exporter`	9140	Экспортер
`r_vstorage_exporter`	Агент	`vision_r_vstorage_exporter`	17090	Экспортер
`mvs_exporter`	Агент	`vision_mvs_exporter`	17060	Экспортер
`vcore_virtualization_exporter`	Агент	`vision_vcore_virtualization_exporter`	17040	Экспортер
`plagent`	На всех узлах	`plagent`	7550	Агент управления конфигурацией

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

Получение версии#

Метод: GET

Путь:

https://<ip-Сервер>/vision/api/v1/version

Описание:

{
  "status": "success",
  "data": { "vision_version": "1.4-287", "components": {} },
  "pagination": null,
  "message": null,
  "error": null
}

Создание токена#

Авторизация: Визион (writer) .

Метод: POST.

Путь:

https://<ip-Сервер>/vision/api/v1/auth/token/

Описание:

{
  "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/

Описание:

{
  "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

Описание:

{
  "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 для получения метрик. Доступны следующие запросы:

/federate;
/labels;
/labels/{label_name}/values;
/query;
/query_range;
/series;
/status/tsdb.

Получение дерева объектов#

Авторизация: Токен.

Метод: GET.

Путь:

https://<ip-Сервер>/vision/api/v1/object/

Описание:

{
  "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>: временной ряд Prometheus селекторам наподобии 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. Настройка Визион для аутентификации сторонних сервисов#

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