Версия: 6.1

Окна обслуживания API

Описание

Режим обслуживания — это механизм временного исключения выбранных измерений глобальных метрик из процесса анализа инцидентов и последующих расчетов состояния сервисов.

Функция используется во время плановых и внеплановых технических работ, например:

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

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

При этом:

исходные значения метрик продолжают рассчитываться
история состояний не изменяется
измерения, соответствующие условиям фильтров, получают признак is_in_maintenance = true
такие измерения исключаются из расчета сервисных метрик и состояния сервисов

Статусы окна обслуживания

Окно обслуживания может находиться в одном из следующих состояний:

Статус	Описание
`planned`	Окно создано и ожидает наступления времени начала обслуживания (`start_at`)
`active`	Обслуживание активно и применяется к измерениям, соответствующим условиям фильтров
`completed`	Обслуживание завершено автоматически по `end_at` или вручную пользователем
`cancelled`	Окно обслуживания было отменено до начала обслуживания

CRUD-операции

Создание окна обслуживания

Создает новое окно обслуживания для одной или нескольких глобальных метрик.

Запрос

Пример запроса

POST _core/rsm/maintenance
{
  "name": "Плановые работы на API заказов",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-*"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ],
  "start_at": "2026-04-16T17:05:00.000Z",
  "end_at": "2026-04-16T19:50:00.000Z"
}

Параметры запроса

Поле	Тип	Обязательное	Описание
`name`	string	Да	Название окна обслуживания. Не должно быть пустым
`groups`	array	Да	Группы фильтров для определения охвата. Должен быть указан как минимум один элемент
`groups[].name`	string	Да	Название группы фильтров. Не должно быть пустым
`groups[].elements`	array	Да	Условия внутри группы. Должен быть указан как минимум один элемент
`groups[].elements[].name`	string	Да	Название измерения. Не должно быть пустым
`groups[].elements[].values`	array[string]	Да	Значения измерения. Пустой массив означает выбор всех значений измерения
`metric_ids`	array[string]	Да	Список глобальных метрик. Должна быть выбрана как минимум одна метрика
`start_at`	datetime	Да	Время начала обслуживания. Значение должно быть позже текущего момента
`end_at`	datetime	Да	Время завершения обслуживания. Значение должно быть позже текущего момента и значения `start_at`

Логика работы фильтров

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

Если массив groups[].elements[].values пуст, фильтр охватывает все значения указанного измерения.

Значения измерений поддерживают шаблоны с подстановочными знаками (wildcard). Это позволяет одним значением фильтра охватить несколько значений измерения, соответствующих указанному шаблону.

Обновление окна обслуживания

Изменяет существующее окно обслуживания.

Запрос

Пример запроса на обновление

PUT _core/rsm/maintenance/{id}
{
  "name": "Плановые работы на API заказов",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-01",
            "app-node-02"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ],
  "start_at": "2026-04-16T17:05:00.000Z",
  "end_at": "2026-04-16T19:50:00.000Z"
}

Параметры запроса

Для изменения параметров используются те же поля, что и при создании окна обслуживания. Дополнительно запрос поддерживает поле state, которое используется для отмены запланированного окна.

Поле	Тип	Обязательное	Описание
`state`	string	Нет	Новый статус окна. Значение `cancelled` отменяет запланированное окно

Правила редактирования зависят от текущего статуса окна:

Статус	Изменение `start_at`	Изменение `end_at`
`planned`	Разрешено. Новое значение должно быть позже текущего момента	Разрешено. Новое значение должно быть позже текущего момента и `start_at`
`active`	Запрещено	Разрешено, если новое значение позже текущего момента
`completed`	Запрещено	Запрещено
`cancelled`	Запрещено	Запрещено

Окна в статусах completed и cancelled редактировать нельзя.

Отмена окна обслуживания

Для отмены окна используется запрос обновления. Отменить можно только окно в статусе planned.

Запрос

PUT _core/rsm/maintenance/{id}
{
  "state": "cancelled"
}

После выполнения запроса окно переходит в статус cancelled и не активируется в запланированное время.

Принудительное завершение окна обслуживания

Принудительно завершает активное окно обслуживания. После выполнения запроса окно переходит в статус completed, а в поле end_at записываются дата и время выполнения запроса.

Запрос

POST _core/rsm/maintenance/{id}/completed

Получение списка окон обслуживания

Возвращает все созданные окна обслуживания.

Запрос

GET _core/rsm/maintenance

В ответе возвращается массив окон обслуживания.

Получение конкретного окна обслуживания

Возвращает информацию о конкретном окне обслуживания.

Запрос

GET _core/rsm/maintenance/{id}

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

Окно обслуживания

{
  "_meta": {
    "id": "0aFWcJ8Ba6VDXX_eQ4PI",
    "created": "2026-07-17T13:48:49.483Z",
    "updated": "2026-07-17T13:52:00.004Z",
    "type": "user",
    "tag_ids": [],
    "from_system": false
  },
  "_permissions": {
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    },
    "owner": "admin",
    "isWritable": true
  },
  "name": "Плановые работы на API заказов",
  "start_at": "2026-07-17T13:49:00.000Z",
  "end_at": "2026-07-17T13:52:00.000Z",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-*"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metrics": [
    {
      "id": "7W6VHZ8BjUVSVN0e2bVN",
      "name": "[prod] Время ответа API заказов",
      "dimension_count": 4
    },
    {
      "id": "KW-lHZ8BjUVSVN0e7Bkc",
      "name": "[prod] Доля ошибочных запросов API заказов",
      "dimension_count": 4
    }
  ],
  "state": "completed"
}

Основные поля ответа

Поле	Описание
`_meta.id`	Идентификатор окна обслуживания
`_meta.created`	Дата и время создания
`_meta.updated`	Дата и время последнего изменения
`_permissions.owner`	Владелец окна обслуживания
`_permissions.isWritable`	Доступность редактирования
`name`	Название окна обслуживания
`start_at`	Время начала обслуживания
`end_at`	Время завершения обслуживания
`groups`	Группы фильтров охвата
`groups[].name`	Название группы фильтров
`groups[].elements`	Условия внутри группы
`groups[].elements[].name`	Название измерения
`groups[].elements[].values`	Значения измерения
`metrics`	Список связанных глобальных метрик
`metrics[].id`	Идентификатор глобальной метрики
`metrics[].name`	Название глобальной метрики
`metrics[].dimension_count`	Количество измерений метрики
`state`	Текущий статус окна обслуживания

Удаление окна обслуживания

Удаляет окно обслуживания в статусе planned или cancelled.

Окна в статусах active и completed удалить нельзя: они уже повлияли на расчет состояния и сохраняются в системе как записи об обслуживании.

Запрос

DELETE _core/rsm/maintenance/{id}

Запросы для отображения и предпросмотра

Проверка покрытия метрик

Используется для предварительной проверки покрытия перед сохранением окна обслуживания.

Позволяет:

определить пересечение измерений выбранных метрик
получить список рядов, соответствующих условиям фильтров
проверить наличие покрытия
показать пользователю предварительный результат применения режима обслуживания

Запрос на проверку покрытия

Запрос

Пример запроса

POST _core/rsm/maintenance/intersection
{
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "host_name",
          "values": [
            "app-node-01",
            "app-node-02"
          ]
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ]
}

Параметры запроса

Поле	Тип	Обязательное	Описание
`groups`	array	Да	Группы фильтров для проверки покрытия. Должен быть указан как минимум один элемент
`metric_ids`	array[string]	Да	Выбранные глобальные метрики. Должна быть выбрана как минимум одна метрика

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

Результат пересечения

{
  "fields": [
    "environment",
    "region",
    "host_name",
    "order_operation"
  ],
  "metric_entities": [
    {
      "title": "[prod] Время ответа API заказов",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-01",
        "order_operation": "create_order"
      }
    },
    {
      "title": "[prod] Время ответа API заказов",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-01",
        "order_operation": "update_order"
      }
    },
    {
      "title": "[prod] Доля ошибочных запросов API заказов",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-02",
        "order_operation": "get_order"
      }
    },
    {
      "title": "[prod] Доля ошибочных запросов API заказов",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-02",
        "order_operation": "cancel_order"
      }
    }
  ]
}

Основные поля ответа

Поле	Описание
`fields`	Список общих измерений (пересечение измерений выбранных глобальных метрик)
`metric_entities`	Список рядов метрик, соответствующих условиям охвата
`metric_entities[].title`	Название глобальной метрики
`metric_entities[].dimensions`	Значения измерений соответствующего ряда

Получение метрик по измерениям

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

Запрос

POST _core/rsm/parent_metrics/dimensions
{
  "dimensions": [
    "environment",
    "region",
    "host_name",
    "order_operation"
  ]
}

В результате возвращаются метрики, которые одновременно содержат измерения environment, region, host_name и order_operation.

Получение подсказок для значений фильтра

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

Запрос

POST _core/rsm/parent_metrics/filter_values
{
  "metric_ids": [],
  "filter": "region",
  "value": "*",
  "size": 50
}

В metric_ids передаются идентификаторы метрик, по которым необходимо объединить значения измерения. Пустой массив означает поиск по всем метрикам. Поле filter содержит название измерения, value — шаблон поиска по его значениям, а size ограничивает количество подсказок в ответе. Значение * возвращает значения без дополнительной фильтрации.

Вводимый в фильтр текст можно передавать в value, чтобы получать подходящие подсказки по мере ввода. Пользователь также может указать произвольное значение, отсутствующее в списке подсказок.

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

{
  "values": [
    "ru-central",
    "ru-northwest",
    "kz-central",
    "by-central"
  ]
}

Получение сущностей глобальной метрики

Возвращает сущности глобальной метрики вместе с их измерениями, текущим состоянием, историей значений и связанными слоями и сервисами. Параметр include_linked_info=true добавляет сведения о режиме обслуживания.

Запрос

GET _core/rsm/parent_metrics/7W6VHZ8BjUVSVN0e2bVN/entities?include_linked_info=true

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

Сущности глобальной метрики

[
  {
    "metric_id": "7W6VHZ8BjUVSVN0e2bVN",
    "entity_id": "12b9e3f4ce87853e44cfbaeb546bda55a8033d71d04504c6d9d57059b9c222bf",
    "entity_title": "environment: production; region: ru-central; host_name: app-node-01; order_operation: create_order",
    "dimensions": {
      "environment": "production",
      "region": "ru-central",
      "host_name": "app-node-01",
      "order_operation": "create_order"
    },
    "layers": [
      {
        "id": "hnDTHZ8BjUVSVN0eRyfS",
        "title": "Инфраструктура API заказов"
      }
    ],
    "services": [
      {
        "id": "K3DUHZ8BjUVSVN0eAi22",
        "title": "Сервис оформления заказов"
      }
    ],
    "value": 3,
    "health_score": 25,
    "severity": "HIGH",
    "trend": [
      {
        "@timestamp": "2026-07-17T13:45:00.000Z",
        "value": null
      },
      {
        "@timestamp": "2026-07-17T13:50:00.000Z",
        "value": 3
      }
    ],
    "is_in_maintenance": true,
    "maintenances": [
      {
        "_meta": {
          "id": "0aFWcJ8Ba6VDXX_eQ4PI",
          "tag_ids": [],
          "created": "2026-07-17T13:48:49.483Z",
          "updated": "2026-07-17T13:52:00.004Z",
          "type": "user",
          "from_system": false
        },
        "name": "Плановые работы на API заказов",
        "start_at": "2026-07-17T13:49:00.000Z",
        "end_at": "2026-07-17T13:52:00.000Z"
      }
    ]
  }
]

Поле is_in_maintenance показывает, находится ли сущность в режиме обслуживания. Если значение равно true, массив maintenances содержит связанные активные и запланированные окна обслуживания, время завершения которых еще не наступило. Для каждого окна возвращаются его идентификатор, название, время начала и завершения.

Устаревшие запросы для получения доступных измерений

Deprecated

Запрос GET _core/rsm/maintenance/metric_dimensions/{metric_id} возвращал измерения конкретной метрики, признак обслуживания и связанные окна обслуживания.

Запрос GET _core/rsm/maintenance/metric_dimensions/ использовался для получения измерений всех метрик и построения формы условий обслуживания.

Оба запроса устарели. Вместо них используйте GET _core/rsm/parent_metrics/{metric_id}/entities?include_linked_info=true.

Описание​

Статусы окна обслуживания​

CRUD-операции​

Создание окна обслуживания​

Запрос​

Параметры запроса​

Обновление окна обслуживания​

Запрос​

Параметры запроса​

Отмена окна обслуживания​

Запрос​

Принудительное завершение окна обслуживания​

Запрос​

Получение списка окон обслуживания​

Запрос​

Получение конкретного окна обслуживания​

Запрос​

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

Основные поля ответа​

Удаление окна обслуживания​

Запрос​

Запросы для отображения и предпросмотра​

Проверка покрытия метрик​

Запрос на проверку покрытия​

Запрос​

Параметры запроса​

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

Основные поля ответа​

Получение метрик по измерениям​

Запрос​

Получение подсказок для значений фильтра​

Запрос​

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

Получение сущностей глобальной метрики​

Запрос​

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

Устаревшие запросы для получения доступных измерений​

Описание

Статусы окна обслуживания

CRUD-операции

Создание окна обслуживания

Запрос

Параметры запроса

Обновление окна обслуживания

Запрос

Параметры запроса

Отмена окна обслуживания

Запрос

Принудительное завершение окна обслуживания

Запрос

Получение списка окон обслуживания

Запрос

Получение конкретного окна обслуживания

Запрос

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

Основные поля ответа

Удаление окна обслуживания

Запрос

Запросы для отображения и предпросмотра

Проверка покрытия метрик

Запрос на проверку покрытия

Запрос

Параметры запроса

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

Основные поля ответа

Получение метрик по измерениям

Запрос

Получение подсказок для значений фильтра

Запрос

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

Получение сущностей глобальной метрики

Запрос

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

Устаревшие запросы для получения доступных измерений