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

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

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

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

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

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

Точка доступа API:

GET /vision/api/v1/version

Пример ответа:

{
  "status": "success",
  "data": {
    "vision_version": "1.9-908",
    "components": {}
  },
  "message": null,
  "next_offset": null,
  "total_count": null,
  "error": null
}

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

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

Точка доступа API:

POST /vision/api/v1/auth/token/

Пример ответа:

{
  "status": "success",
  "data": {
    "jti": "c5adf94c-1e21-4581-b912-d33d089fd4bf",
    "name": "<название>",
    "created_at": "2025-12-29T15:15:01.613554+03:00",
    "token": "*****"
  },
  "message": null,
  "next_offset": null,
  "total_count": null,
  "error": null
}

Просмотр списка токенов#

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

Точка доступа API:

GET /vision/api/v1/auth/token/

Пример ответа:

{
  "status": "success",
  "data": [
    {
      "jti": "c5adf94c-1e21-4581-b912-d33d089fd4bf",
      "name": "<название>",
      "created_at": "2025-12-29T15:15:01.613554+03:00"
    }
  ],
  "message": null,
  "next_offset": null,
  "total_count": null,
  "error": null
}

Перевыпуск токена#

Выполняется путем отзыва старого токена и созданием нового с тем же названием.

Отзыв токена#

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

Точка доступа API:

POST /vision/api/v1/auth/token/revoke

Пример ответа:

{
  "status": "success",
  "data": {
    "jti": "c5adf94c-1e21-4581-b912-d33d089fd4bf",
    "name": "<название>",
    "created_at": "2025-12-29T15:15:01.613554+03:00"
  },
  "message": null,
  "next_offset": null,
  "total_count": null,
  "error": null
}

Работа с БДВР#

Авторизация с помощью токена.

Точка доступа API:

GET /vision/api/v1/tsdb/*

Описание: предоставляет доступ к API VictoriaMetrics для получения метрик. Доступны следующие запросы:

  • /federate;

  • /labels;

  • /labels/{label_name}/values;

  • /query;

  • /query_range;

  • /series;

  • /status/tsdb.

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

Авторизация с помощью токена.

Точка доступа API:

GET /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"
      }
    }
  ]
}

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

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

Authorization: Bearer <token>

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

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

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

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

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

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

  • имя пользователя: vision;

  • пароль: skala-r.

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

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

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

Эндпоинт:

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...

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

Эндпоинт:

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

Метки#

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

  • _pak_id — идентификатор ПАК.

  • _target_id — идентификатор объекта (задачи) мониторинга.

  • _target_type — тип объекта (задачи) мониторинга. В зависимости от типа (NODE — узел, VM — виртуальная машина, COMM — коммутатор, SERVICE — сервис) и особенностей объекта (задачи) мониторинга метрика получает дополнительные служебные метки:

    • _module_id — идентификатор модуля ПАК.

    • _node_id — идентификатор узла ПАК.

    • _vm_id — идентификатор служебной виртуальной машины ПАК.

    • _comm_id — идентификатор коммутатора ПАК.

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

API для работы с данными#

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.

Prometheus#

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

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

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.

Запросы# 

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