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

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

Продукт предоставляет 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 для шаблона конфигурации кластера:

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

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 для шаблона экземпляра мониторинга:

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

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 необходимо для начальной загрузки и последующей модификации значений пользовательских свойств объектов мониторинга.

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

1. Пользовательские свойства должны быть задекларированы до загрузки в них значений (в противном случае обработка документа будет прервана с ошибкой).

2. Пользовательские свойства становятся доступны в Оперативном центре для отображения, группировки и поиска после добавления в custom_properties.

3. Для удаления пользовательских свойств объекта мониторинга необходимо установить custom_properties = null.

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

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

• По умолчанию правом на конфигурацию метрик объекта мониторинга обладают только операторы, наделенные ролью «Администратор мониторинга».

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

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

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

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

1. Параметр должен быть из числа предопределенных, иначе обработка документа будет прервана с ошибкой.

2. Значение параметра должно находиться в границах допустимых значений, иначе обработка документа будет прервана с ошибкой.

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

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

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

Если 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 описывает изменения атрибутов одного объекта мониторинга, в БД изменения применяются последовательно (в соответствии с порядком объектов в массиве).

Каждый объект массива 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:

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

Заполнение 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