Быстрый старт

Пакетная загрузка кластеров СУБД и экземпляров мониторинга

Продукт предоставляет REST API для пакетной загрузки кластеров СУБД и экземпляров мониторинга.

Пользователь или автоматизированная система, обладающие ролью для массовой загрузки, загружают подготовленный файл с JSON-описанием шаблонов кластеров СУБД и экземпляров мониторинга. Также отдельно указывается, для каких пользователей будут доступны загружаемые шаблоны. На основе данного описания формируются шаблоны кластеров и экземпляров мониторинга в области видимости выбранных пользователей. Далее пользователь может, обогатив данные шаблоны информацией, преобразовать их кластера СУБД и экземпляры мониторинга.

Пример файла templates.json в формате JSON для шаблона конфигурации кластера:

[
  {
    "name": "cluster_example",
    "usernames": ["username"],
    "connections": [
      {
        "name": "server_example",
        "host": "10.xx.xx.xx",
        "port": 5555,
        "db_name": "db_name_example"
      }
    ]
  }
]

Описание содержания запроса в формате JSON для шаблона конфигурации кластера:

Параметр	Пример	Описание
`name`	`cluster_example`	Название кластера
`usernames`	`username`	Содержит массив имен пользователей, которым будет доступен шаблон
`connections.name`	`server_example`	Название СУБД
`connections.host`	`10.xx.xx.xx`	Адрес СУБД
`connections.port`	`5555`	Порт СУБД
`connections.db_name`	`db_name_example`	Имя БД для подключения

Пример запроса командной строки для создания шаблона конфигурации кластера:

curl -X POST -H "Authorization: Basic ${token}" https://${kintsugi_host}/backend/templates:bulkCreate -H "Content-Type: application/json" @templates.json

Пример файла monitorings.json в формате JSON для шаблона экземпляра мониторинга:

{
  "params": {
    "version": 1,
    "duplicate_handling": {
      "asset_identity": {
        "type": "property_list",
        "property_keys": [
          "host",
          "port",
          "databases"
        ]
      },
      "strategy": "skip"
    }
  },
  "data": [
    {
      "name": "bulk_example-1",
      "host": "10.XX.XX.X",
      "master": "postgres",
      "port": 5555,
      "login": "login_example",
      "inuse": false,
      "databases": null,
      "comment": null,
      "ssl_mode": null
    }
  ]
}

примечание

* Форма запроса является типовой и может меняться в зависимости от настроек процесса аутентификации в программном окружении.

Описание содержания запроса в формате JSON для шаблона экземпляра мониторинга:

Параметр	Пример	Описание
`params.version`	`1`	Номер версии параметра запроса
`params.duplicate_handling.asset_identity.type`	`property_list`	Тип определителя актива
`params.duplicate_handling.asset_identity.property_keys`	`"host", "port", "databases"`	Массив параметров, определяющих дубликаты
`params.duplicate_handling.strategy`	`skip`	Стратегия обработки дубликатов. Если задано значение: `skip`, то дубликаты игнорируются, `insert`, то дубликаты сохраняются
`data.name`	`bulk_example`	Название СУБД
`data.host`	`10.XX.XX.X`	Адрес СУБД
`data.master`	`postgres`	БД для подключения
`data.port`	`5555`	Порт СУБД
`data.login`	`login_example`	Имя пользователя СУБД
`data.inuse`	`true`	Включение или отключение наблюдения объекта мониторинга (`true`/`false`)
`data.databases`	`null`	Список наблюдаемых БД, заданных через запятую
`data.comment`	`null`	Комментарий
`data.ssl_mode`	`null`	Режим SSL. Возможен выбор любого из перечисленных режимов: `disable`, `allow`, `prefer`, `require`, `verify-ca`, и `verify-full`

Пример запроса командной строки для создания экземпляров мониторинга:

curl -X POST -H "Authorization: Basic ${token}" https://${kintsugi_host}/backend/monitorings:bulkCreate -H "Content-Type: application/json" @monitorings.json

Массовое обновление части конфигурации объектов мониторинга

Продукт предоставляет REST API для частичного обновления большого количества объектов мониторинга.

Запрос состоит из массива data. Каждый элемент массива отвечает за поиск и изменение одного объекта мониторинга. Изменяемые данные содержатся в asset_patch.

Операция частичного обновления поддерживает ограниченный набор полей и операций над ними:

Поле	Изменение	Удаление	Описание
`custom_properties`	Да	Да	Добавление/изменение/удаление пользовательских свойств объекта мониторинга
`owners`	Да	Да	Добавление/изменение/удаление прав на конфигурацию метрик объекта мониторинга
`pi_parameters`	Да	Да	Добавление/изменение/удаление индивидуальных параметров хранилища данных о производительности СУБД объекта мониторинга

При обновлении custom_properties, owners и/или pi_parameters другие поля объекта мониторинга (логин, пароль, сертификаты и т.п.) остаются без изменений.

Добавление и заполнение поля custom_properties необходимо для начальной загрузки и последующей модификации значений пользовательских свойств объектов мониторинга.

Рекомендации по работе с custom_properties:

Пользовательские свойства необходимо задекларировать до загрузки в них значений (в противном случае обработка документа будет прервана с ошибкой).
Пользовательские свойства становятся доступны в Оперативном центре для отображения, группировки и поиска после добавления в custom_properties.
Для удаления пользовательских свойств объекта мониторинга необходимо установить custom_properties = null.

Права на конфигурацию метрик объекта мониторинга owners:

Для каждого объекта мониторинга можно определить список пользователей, являющихся его владельцами. Владелец объекта имеет право конфигурировать метрики объекта мониторинга, даже если он не обладает ролью «Администратор мониторинга».
По умолчанию правом на конфигурацию метрик объекта мониторинга обладают только операторы, наделенные ролью «Администратор мониторинга».
Для выдачи права на конфигурацию метрик объекта мониторинга операторам с ролью «Пользователь» необходимо добавить и заполнить поле owners, в массиве которого указать нужного пользователя.
Для удаления права на конфигурацию метрик объекта мониторинга у всех пользователей необходимо установить owners = null.

Изменение поля pi_parameters необходимо для индивидуальной настройки работы хранилища данных о производительности СУБД на уровне объекта мониторинга.

Рекомендации по работе с pi_parameters:

Параметр должен быть из числа предопределенных, иначе обработка документа будет прервана с ошибкой.
Значение параметра должно находиться в границах допустимых значений, иначе обработка документа будет прервана с ошибкой.
Параметры становятся доступны на вкладке Управление порогами и сбором данных метрик в разделе Производительность СУБД для отображения и управления.
Для удаления параметров хранилища данных о производительности СУБД объекта мониторинга необходимо установить pi_parameters = null.

Доступные для изменения на уровне объекта мониторинга параметры хранилища данных о производительности СУБД:

Параметр	Тип	Допустимые значения	Описание
`storage_type`	Перечисление	`"in-memory", "persistent"`	Тип хранилища. `"in-memory"` – хранение данных в оперативной памяти, `"persistent"` – хранение данных в персистентной СУБД
`history_depth_seconds`	Целочисленный	`[1; 2147483647]`	Максимальная глубина хранения данных в секундах
`storage_size_limit_bytes`	Целочисленный	`[1; 18446744073709551615]`	Максимальный размер хранилища в байтах. Доступно только в режиме `"in-memory"`
`activity_resolution_sec`	Целочисленный	`[1; 4294967295]`	Разрешающая способность активности в секундах. Определяет частоту сохранения агрегированной статистики активных сессий в хранилище
`query_max_length_bytes`	Целочисленный	`[1; 4294967295]`	Максимальная длина текста запроса в байтах. Текст запросов будет обрезан для `query_max_length_bytes`
`gather_locks`	Логический	`true, false`	Индикатор активности сбора данных по блокировкам
`locks_interval_sec`	Целочисленный	`[1; 4294967295]`	Интервал сбора блокировок (секунды). Определяет частоту сохранения данных о блокировках в хранилище в секундах

Если custom_properties, owners и/или pi_parameters отсутствует в asset_patch, то никаких изменений не произойдет.

При этом в теле запроса должен быть запрос на изменение хотя бы одного из полей патча (custom_properties, owners, pi_parameters или их комбинации).

Если значение поля патча (custom_properties, owners или pi_parameters) = null - будет произведена операция удаления значений этого поля актива в БД.

Таким образом с помощью одного API-вызова осуществляются операции по созданию/изменению/удалению пользовательских свойств объекта мониторинга, его владельцев и индивидуальных параметров хранилища данных о производительности СУБД.

Идентификация объекта мониторинга происходит либо по asset_id, либо по связке host + port.

Возможные ошибки обновления части конфигурации объекта мониторинга:

не удалось найти объект мониторинга, используя в запросе предоставленный способ идентификации в поле asset_selector;
в БД обнаружено дублирование asset_id;
в БД обнаружено дублирование объекта мониторинга с одинаковыми значениями полей host и port;
превышен лимит на количество пользовательских свойств у объекта мониторинга;
превышен лимит на количество владельцев объекта мониторинга;
указанного пользовательского свойства нет в БД;
длина пользовательского свойства превышена.

Пример файла assets_bulk_patch.json в формате JSON для массового обновления части конфигурации объектов мониторинга:

{
  "data": [
    {
      "asset_selector": {
        "asset_id": "6476e34f-8850-48a6-a426-ff77655354c4"
      },
      "asset_patch": {
        "custom_properties": [
          {
            "property_key": "custom_key_1",
            "property_value": "value_1"
          },
          {
            "property_key": "custom_key_2",
            "property_value": "value_2"
          }
        ],
        "owners": [
          "user_1",
          "user_2"
        ],
        "pi_parameters": [
          {
            "parameter_key": "gather_locks",
            "parameter_value": true
          },
          {
            "parameter_key": "locks_interval_sec",
            "parameter_value": 5
          }
        ]
      }
    },
    {
      "asset_selector": {
        "asset_type": "pg",
        "host": "10.xx.xx.xx",
        "port": 5555
      },
      "asset_patch": {
        "custom_properties": [
          {
            "property_key": "custom_key_1",
            "property_value": "value_1"
          },
          {
            "property_key": "custom_key_2",
            "property_value": "value_2"
          }
        ],
        "owners": [
          "user_1"
        ],
        "pi_parameters": [
          {
            "parameter_key": "history_depth_seconds",
            "parameter_value": 72000
          }
        ]
      }
    }
  ]
}

Описание содержания запроса:

Параметр	Пример	Описание
`data`	-	Список объектов мониторинга на частичное обновление
`asset_selector`	-	Селектор объекта мониторинга
`asset_id`	`6476e34f-8850-48a6-a426-ff77655354c4`	Идентификатор объекта мониторинга в формате UUID
`asset_type`	`pg`	Тип объекта мониторинга. Значение `pg` - обязательное
`host`	`10.xx.xx.xx`	Адрес СУБД
`port`	`5555`	Порт СУБД
`asset_patch`	-	Набор полей для частичного обновления конфигурации объекта мониторинга
`custom_properties`	-	Список пользовательских свойств объекта мониторинга
`property_key`	`custom_key_1`	Ключ пользовательского свойства
`property_value`	`value_1`	Значение пользовательского свойства
`owners`	`["user_1"]`	Список владельцев объекта мониторинга
`pi_parameters`	-	Список индивидуальных параметров хранилища данных о производительности СУБД
`parameter_key`	`gather_locks`	Ключ индивидуального параметра хранилища данных о производительности СУБД
`parameter_value`	`true`	Значение индивидуального параметра хранилища данных о производительности СУБД

Каждый объект в массиве data описывает изменения атрибутов одного объекта мониторинга, в БД изменения применяются последовательно (в соответствии с порядком объектов в массиве).

Каждый объект массива data содержит две части:

asset_selector - служит для поиска объекта.
asset_patch - набор полей для операции частичного обновления объекта мониторинга.

Заполнение asset_selector поддерживает два варианта поиска:

по идентификатору актива (asset_id);
по сетевому адресу и порту (host, port).

Указанному asset_selector должен соответствовать один объект мониторинга. Если в результате поиска по сетевому адресу и порту будет найдено более одного подходящего объекта, то обработка будет прервана сообщением об ошибке.

Заполнение asset_patch:

custom_properties - добавляется в asset_patch, если необходимо добавить/изменить/удалить пользовательские свойства объекта мониторинга;
owners - добавляется в asset_patch, если необходимо добавить/изменить/удалить владельцев объекта мониторинга.
pi_parameters - добавляется в asset_patch, если необходимо добавить/изменить/удалить индивидуальные параметры хранилища данных о производительности СУБД.

Заполнение custom_properties:

Данный объект содержит новые значения для пользовательских свойств объекта.

При обновлении содержимое custom_properties полностью подменяет предыдущий набор значений пользовательских свойств объекта (если в custom_properties какое-то значение какого-либо атрибута не было указано, то его предыдущее значение будет удалено из БД).

Заполнение owners:

Данный объект содержит имена пользователей, являющихся владельцами объекта мониторинга.

Внимание!

В качестве имени пользователя необходимо указывать значение того поля JWT-токена, которое задано в конфигурационном параметре username_claim_name сервиса curator.

Заполнение pi_parameters:

Данный объект содержит новые значения для индивидуальных параметров хранилища данных о производительности СУБД на уровне объекта мониторинга.

При обновлении содержимое pi_parameters полностью заменяет предыдущие значения индивидуальных параметров хранилища данных о производительности СУБД объекта (если в pi_parameters какое-то значение какого-либо параметра не было указано, то его предыдущее значение будет удалено из БД).

Пример запроса командной строки для массового обновления части конфигурации объектов мониторинга:

curl -X POST -H "Authorization: Basic ${token}" https://${kintsugi_host}/assets:bulkPatch -H "Content-Type: application/json" @assets_bulk_patch.json

Пакетная загрузка кластеров СУБД и экземпляров мониторинга​

Массовое обновление части конфигурации объектов мониторинга​

Пакетная загрузка кластеров СУБД и экземпляров мониторинга

Массовое обновление части конфигурации объектов мониторинга