Стандарты сервисов, готовность и события каталога#

Этот документ описывает модель готовности каталога сервисов в IncidentRelay: стандарты сервисов, проверки готовности, внутрипроцессный адаптер событий каталога и API хронологии сервиса.

Цели#

Стандарты сервисов определяют, что сервис должен иметь, прежде чем он будет считаться операционно готовым. Стандарт применяется к сервисам с помощью селекторов applies_to. Готовность оценивает все стандарты, соответствующие сервису, и сохраняет агрегированное состояние готовности сервиса.

События каталога предоставляют единую внутреннюю точку входа для изменений каталога сервисов. Слой представления или сервиса выпускает доменное событие, а адаптер записывает события хронологии и запускает согласование готовности, когда это необходимо.

КопироватьService/standard action
└── emit_service_catalog_event(...) or emit_group_service_catalog_event(...)
    ├── writes ServiceEvent when the event is service-scoped
    └── runs readiness reconciliation

ServiceEvent намеренно ограничен областью сервиса. Изменения уровня группы, такие как стандарты/проверки, не создают отдельной строки хронологии для каждого сервиса. Вместо этого они запускают согласование готовности для группы. Если пакет готовности сервиса создаётся или изменяется, оценщик готовности записывает события хронологии сервиса.

Основные концепции#

Стандарт сервиса#

Стандарт — это именованный набор проверок готовности для группы.

Важные поля:

applies_to#

applies_to — это объект. Пустой объект означает, что стандарт применяется ко всем сервисам в группе.

Поддерживаемые ключи селектора:

Пример:

Копировать{
  "kinds": ["technical"],
  "lifecycles": ["production"],
  "tiers": ["tier_1", "tier_2"],
  "criticalities": ["critical", "high"]
}

Проверка стандарта#

Проверка — это одно требование внутри стандарта.

Важные поля:

Поддерживаемые типы проверок:

Состояние готовности#

Состояние готовности — это текущий агрегат для одного сервиса.

Статусы:

Состояние содержит оценку и счётчики сбоев:

Копировать{
  "status": "not_ready",
  "score": 72,
  "standards_count": 1,
  "checks_count": 6,
  "failed_count": 2,
  "failed_required_count": 1,
  "failed_critical_count": 1,
  "batch_uid": "...",
  "evaluated_at": "2026-06-28T09:32:10Z"
}

Встроенный пресет#

Эндпоинт:

КопироватьPOST /api/services/standards/presets/basic-operational

Пресет создаёт/восстанавливает basic-operational-readiness для группы. Он применяется к production-техническим сервисам и проверяет основные операционные требования:

• активный владелец / заинтересованная сторона по умолчанию;
• политика эскалации с правилами;
• политика уведомлений с правилами и каналами;
• покрытие маршрутом или сопоставлением;
• хотя бы один runbook;
• граф зависимостей без циклов.

Пресет выпускает событие каталога группы и согласует готовность для группы.

Адаптер событий каталога#

Адаптер находится в:

Копироватьapp/services/service_catalog/events.py

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

События уровня сервиса#

Копироватьemit_service_catalog_event(
    service,
    category="configuration",
    event_type="service_runbook.created",
    title="Service runbook created",
    summary=runbook.title,
    source_ref=f"service_runbook:{runbook.id}",
    external_url=runbook.url,
    actor_user=current_user(),
    payload={"runbook": service_runbook_snapshot(runbook)},
    readiness_trigger="service_runbook_created",
)

Это записывает строку ServiceEvent и по умолчанию согласует готовность.

События уровня группы#

Копироватьemit_group_service_catalog_event(
    group_id,
    category="readiness",
    event_type="service_standard.updated",
    title="Service standard updated",
    actor_user=current_user(),
    before=before_snapshot,
    after=after_snapshot,
    readiness_trigger="standard_updated",
)

Это не записывает отдельную строку хронологии, потому что ServiceEvent ограничен областью сервиса. Оно согласует готовность группы.

Ручное согласование готовности#

Копироватьreconcile_service_catalog_readiness(
    service,
    trigger="manual_evaluate",
    actor_user=current_user(),
)

Используйте это для явных действий API/UI Evaluate readiness, когда не должно создаваться дополнительное доменное событие.

Области готовности#

Соглашения об именовании событий#

Используйте стабильные имена с точками:

Копироватьservice.created
service.updated
service.deleted
service_owner.created
service_owner.updated
service_owner.deleted
service_link.created
service_link.updated
service_link.deleted
service_runbook.created
service_runbook.updated
service_runbook.deleted
service_dependency.created
service_dependency.updated
service_dependency.deleted
service_dependency.downstream_created
service_dependency.downstream_updated
service_dependency.downstream_deleted
service_match_rule.created
service_match_rule.updated
service_match_rule.deleted
service_standard.created
service_standard.updated
service_standard.deleted
service_standard_check.created
service_standard_check.updated
service_standard_check.deleted
service_standard_preset.applied
readiness.evaluated
readiness.score_changed

Рекомендуемые категории:

API хронологии#

Эндпоинт:

КопироватьGET /api/services/{service_id}/timeline

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

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

Копировать{
  "items": [
    {
      "id": 123,
      "uid": "...",
      "service_id": 10,
      "group_id": 1,
      "team_id": 2,
      "category": "configuration",
      "event_type": "service_runbook.created",
      "title": "Service runbook created",
      "summary": "RabbitMQ cluster partition",
      "source": "incidentrelay",
      "source_ref": "service_runbook:42",
      "external_url": "https://docs.example.com/runbooks/rabbitmq",
      "actor": {
        "type": "user",
        "user_id": 7,
        "display_name": "Alice",
        "email": "alice@example.com",
        "label": null
      },
      "severity": null,
      "status": null,
      "occurred_at": "2026-06-28T09:32:10Z",
      "recorded_at": "2026-06-28T09:32:10Z",
      "schema_version": 1,
      "payload": {
        "runbook": {
          "id": 42,
          "title": "RabbitMQ cluster partition"
        }
      }
    }
  ],
  "next_cursor": {
    "before": "2026-06-28T09:32:10Z",
    "before_id": 123
  }
}

Сводка по API#

Стандарты#

Проверки#

Готовность#

События#

Управление доступом#

• Стандарты ограничены областью группы.
• Просмотр списка стандартов требует доступа на чтение к группе.
• Создание/обновление/удаление стандартов и проверок требует доступа на запись к группе.
• Готовность сервиса и хронология требуют доступа на чтение к команде сервиса.
• Ручная оценка готовности требует доступа на запись к команде сервиса.

Ответы об ошибках#

Распространённые коды ошибок:

Контрольный список реализации#

• Используйте emit_service_catalog_event() для изменений уровня сервиса.
• Используйте emit_group_service_catalog_event() для изменений стандарта/проверки/пресета.
• Используйте reconcile_service_catalog_readiness() для ручной оценки без отдельного доменного события.
• Оставляйте write_audit(...) в представлениях как журнал аудита безопасности/API.
• Не записывайте события стандартов уровня группы напрямую в хронологию каждого сервиса.
• Добавляйте снимки в app/services/service_catalog/snapshots.py при введении нового типа объекта каталога.