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

Настройка

Версия v2.5.0 · Обновлено

Настройка#

IncidentRelay читает путь к файлу конфигурации из:

INCIDENTRELAY_CONFIG_FILE

Пример:

export INCIDENTRELAY_CONFIG_FILE=/etc/incidentrelay/incidentrelay.conf

Для systemd:

Environment=INCIDENTRELAY_CONFIG_FILE=/etc/incidentrelay/incidentrelay.conf

Для Docker Compose:

environment:
  INCIDENTRELAY_CONFIG_FILE: /etc/incidentrelay/incidentrelay.conf

Старое имя ONCALL_CONFIG_FILE использовать не следует.

Переопределение через переменные окружения#

Любой параметр из файла конфигурации можно также задать переменной окружения INCIDENTRELAY__<SECTION>__<OPTION>, где секция и параметр записываются в верхнем регистре. Переменная имеет приоритет над файлом:

export INCIDENTRELAY__DATABASE__PASSWORD=replace-with-the-database-password
export INCIDENTRELAY__LOGGING__LEVEL=DEBUG

Чтобы прочитать значение из файла, добавьте к имени __FILE и укажите путь. Так можно использовать секреты Docker и Kubernetes или тома Secrets Store CSI, не записывая секреты в incidentrelay.conf:

export INCIDENTRELAY__DATABASE__PASSWORD__FILE=/run/secrets/db-password

Перевод строки в конце файла игнорируется. Задавать одновременно переменную и её форму __FILE нельзя — это ошибка. Для systemd поместите переменные в EnvironmentFile=.

Если main.secret_key задан через переменную окружения, пустые main.secret_encryption_key, auth.jwt_secret, mattermost.action_secret и voice.callback_secret берут его значение, а не генерируются Docker entrypoint.

main.secret_encryption_key шифрует секреты, которые хранятся в базе, поэтому менять его после первого запуска нельзя — неважно, задан он в файле конфигурации, в переменной окружения или через __FILE. Если он пустой, IncidentRelay шифрует ключом main.secret_key, и тогда то же самое относится к нему. Если ключ шифрования изменился, Docker entrypoint не запустит сервис: верните прежний ключ. Сменить ключ напрямую нельзя. Entrypoint сравнивает ключ с хэшем (с солью), который хранит в /var/lib/incidentrelay, поэтому проверка работает, только если этот каталог сохраняется между перезапусками.

В [voice_provider], где набор параметров зависит от провайдера, переменная только переопределяет параметр, который есть в файле, и имя параметра сохраняет написание из файла. Новых параметров переменные туда не добавляют:

[voice_provider]
apiKey =
export INCIDENTRELAY__VOICE_PROVIDER__APIKEY=replace-with-the-api-key

Параметры провайдера также могут ссылаться на переменную напрямую, например api_token = ${VOICE_API_TOKEN}, см. Настройка голосового провайдера.

Основной секрет и секрет аутентификации#

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

openssl rand -hex 32
openssl rand -hex 32
[main]
secret_key = замените-на-первое-случайное-значение

[auth]
jwt_secret = замените-на-второе-случайное-значение
jwt_cookie_secure = true

Параметр secret_key относится к секции [main], а не [server]. Параметр jwt_secret относится к [auth]. Не используйте одно значение для обоих параметров. При HTTPS в public_base_url установите jwt_cookie_secure = true.

Секция server#

[server]
host = 0.0.0.0
port = 8080
public_base_url = https://incidentrelay.example.com
ПараметрОписание
hostАдрес, к которому привязывается веб-сервис
portHTTP-порт
public_base_urlВнешний URL, используемый в ссылках алертов, кнопках и колбэках

В продакшене public_base_url должен быть реальным внешним HTTPS-URL.

База данных: SQLite#

[database]
type = sqlite
name = /var/lib/incidentrelay/incidentrelay.db

[sqlite]
wal = true
busy_timeout = 5000

SQLite подходит для небольших self-hosted инсталляций. При использовании SQLite оставляйте один веб-воркер.

База данных: PostgreSQL#

[database]
type = postgresql
host = 127.0.0.1
port = 5432
name = incidentrelay
user = incidentrelay
password = change-me

Используйте PostgreSQL для более крупных инсталляций, высокого объёма алертов, нескольких веб-воркеров или долгосрочных продакшен-развёртываний.

Политика исходящих HTTP-подключений#

IncidentRelay защищает исходящие HTTP-запросы к адресам, заданным администратором, от SSRF. По умолчанию запрещены private, loopback, link-local, multicast, reserved и unspecified адреса назначения.

Политика задаётся в секции [security]:

[security]
outbound_private_network_allowlist =
outbound_http_max_redirects = 3
outbound_http_max_response_bytes = 1048576

outbound_private_network_allowlist — список IPv4/IPv6-адресов и CIDR-сетей, разделённых запятыми или точками с запятой. Эти адреса явно разрешаются для исходящих запросов, даже если они относятся к private или другим обычно запрещённым диапазонам.

Примеры:

# Только один внутренний сервис.
outbound_private_network_allowlist = 192.168.50.10/32
# Несколько разрешённых внутренних сетей/адресов.
outbound_private_network_allowlist = 10.20.0.0/16,192.168.50.10/32,fd00:1234::/48

Отдельный IP можно указать и без длины префикса, однако /32 для IPv4 и /128 для IPv6 явно показывают область разрешения. Используйте максимально узкие диапазоны вместо разрешения всей private-сети.

Эта политика используется общим клиентом исходящих HTTP-запросов, в том числе при загрузке OIDC metadata и JWKS, а также для исходящих интеграций: generic/Teams/Discord webhooks, Slack webhooks и запросов к Mattermost API. Это не allowlist имён хостов: IncidentRelay сначала разрешает DNS-имя, затем проверяет полученные IP-адреса.

Для DNS-имени каждый адрес, возвращённый DNS, должен быть публичным или явно разрешённым. Если хотя бы один адрес запрещён, запрос блокируется целиком. Целевой адрес каждого redirect разрешается через DNS и проверяется повторно.

Влияние обновления на 2.1

В IncidentRelay 2.1 эта политика применяется к исходящим запросам.

Поэтому после обновления с 1.2 существующий внутренний OIDC metadata/JWKS

endpoint или исходящая интеграция может перестать работать, даже если URL

не менялся. До обновления разрешите внутренние endpoints с хоста/pod

IncidentRelay и добавьте только необходимые IP или CIDR.

Например, если внутренний identity provider разрешается в 10.42.7.15:

[security]
outbound_private_network_allowlist = 10.42.7.15/32

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

Allowlist меняет только сетевую политику назначения. Он не отключает проверку HTTPS-сертификата и не добавляет доверие к приватному центру сертификации. Для внутренних HTTPS endpoints с private CA этот CA также должен быть установлен в trust store операционной системы или контейнера.

Trace обработки алертов#

Глобальный уровень детализации Explain Trace задаётся в [alerts]:

[alerts]
explain_trace_level = full

Поддерживаются full, compact и disabled. full сохраняет текущее подробное поведение. compact сохраняет последовательность шагов обработки, но не записывает input_summary, payload результата и data отдельных шагов. disabled вообще не создаёт строки Alert Explain Trace. Глобальное правило Event Orchestration может переопределить значение для совпавших событий действием set_trace_level.

История событий алерта#

Историю входящих событий дочерних алертов можно настраивать независимо от самого lifecycle:

[alerts]
event_history = full

Поддерживаются full, initial и disabled. full сохраняет входящие события created, updated и resolved дочерних алертов. initial сохраняет только первое событие created. disabled не сохраняет эти входящие history-записи. При этом обновление состояния алерта, grouping, notifications, escalation и resolution продолжают работать во всех режимах. Operational timeline — acknowledgement, comments, reminders, maintenance, correlations, responders и stakeholders — сохраняется всегда.

Global и Service Event Orchestration могут переопределить значение для совпавших событий действием set_alert_event_history. Если несколько совпавших actions задают уровень, применяется последнее действие.

Задержка уведомления о восстановлении#

Можно отложить внешние уведомления resolved для входящих алертов и восстановившихся heartbeat, не задерживая изменение статуса AlertGroup:

[alerts]
recovery_notification_delay_seconds = 300

По умолчанию 0: уведомления отправляются как раньше. Значение ограничено диапазоном 0–86400 секунд и не зависит от set_grouping.reopen_window_seconds в Event Orchestration. Отложенное уведомление сохраняется в очереди AlertGroup и отменяется при повторном открытии группы. Повторный resolved не переносит время отправки. Ручной Resolve отправляет уведомления сразу.

Scheduler должен быть запущен. Уже отправленное сообщение отозвать нельзя; после сбоя во время внешней доставки теоретически возможен повтор сообщения, если провайдер не поддерживает идемпотентность. Для синхронизации с reopen worker удерживает транзакцию на время доставки. При высокой нагрузке или медленных каналах предпочтительнее PostgreSQL, а не SQLite.

Scheduler для Alert Shelving#

Временные shelves AlertGroup завершаются scheduler-процессом:

[alerts]
shelve_lifecycle_check_interval_seconds = 30
shelve_lifecycle_batch_size = 100

check_interval_seconds задаёт частоту обработки истёкших shelves, а batch_size ограничивает один проход. Scheduler должен быть запущен, если используется timed shelving. Shelving приостанавливает notifications, reminders и escalation, но не меняет технический status AlertGroup и service/business impact. Подробнее: Shelving.

Политика хранения данных#

В IncidentRelay 2.1 все новые retention-настройки находятся в одной секции:

[retention]
alert_days = 30
# explain_trace_days = 30
# orchestration_execution_days = 30
cleanup_interval_seconds = 86400
batch_size = 500

alert_days = 0 используется по умолчанию и хранит завершённую историю alerts бессрочно. Explain Trace и обычные Event Orchestration executions наследуют alert_days, если для них не задан отдельный override. Точные правила удаления и совместимость при обновлении описаны в разделе Политика хранения данных.

Секция SMTP#

Каналы уведомлений по email используют глобальные настройки SMTP. Транспорт SMTP не настраивается отдельно для каждого канала.

[smtp]
host = 127.0.0.1
port = 25
from = incidentrelay@example.com
use_tls = false
user =
password =

Для локального ретранслятора без аутентификации оставьте user и password пустыми.

Для SMTP-сервера с аутентификацией:

[smtp]
host = smtp.example.com
port = 587
from = incidentrelay@example.com
use_tls = true
user = incidentrelay@example.com
password = change-me

По умолчанию Email-канал отправляет уведомления на адрес пользователя из профиля. Можно настроить recipient_mode (fallback или fixed) и recipient_email; SMTP остаётся глобальным.

Прокси для Telegram#

Если окружение требует прокси для вызовов Telegram Bot API, настройте его глобально. Значения токенов держите в конфигурации канала, а не в глобальной конфигурации.

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

Секция voice#

[voice]
provider = stub
providers_dir = /usr/local/lib/incidentrelay/voice_providers
callback_secret = change-me
ПараметрОписание
providerИмя голосового провайдера
providers_dirКаталог с модулями пользовательских провайдеров
callback_secretСекрет, используемый для проверки колбэков

Уведомления голосовым вызовом отправляются на номер телефона из профиля назначенного пользователя.

Секция browser push#

Браузерные push-уведомления — это уведомления уровня профиля для PWA/браузера. Они не настраиваются как каналы уведомлений.

[browser_push]
enabled = true
vapid_public_key = CHANGE_ME_PUBLIC_KEY
vapid_private_key = /etc/incidentrelay/vapid/private_key.pem
vapid_subject = mailto:admin@example.com
action_token_ttl_seconds = 900
ПараметрОписание
enabledВключает или отключает браузерные push-уведомления глобально
vapid_public_keyПубличный ключ VAPID, возвращаемый браузеру для PushManager.subscribe()
vapid_private_keyПриватный ключ VAPID или путь к PEM-файлу, используемый сервером для отправки сообщений Web Push
vapid_subjectКонтактный URI, включаемый в claims VAPID, обычно mailto:admin@example.com
action_token_ttl_secondsВремя жизни одноразовых токенов ACK/Resolve/Shelve/Unshelve, встраиваемых в push-уведомления

После изменения настроек браузерных push-уведомлений перезапустите веб-сервис. Перезапустите также планировщик, если в вашей инсталляции он отправляет уведомления.

Подробнее: Браузерные push-уведомления.

Секция metrics#

IncidentRelay может отдавать метрики Prometheus по GET /metrics:

[metrics]
enabled = true
auth_token = replace-with-a-random-value
ПараметрОписание
enabledОтдает GET /metrics в текстовом формате Prometheus. По умолчанию false, endpoint отвечает 404
auth_tokenЕсли задан, запросы должны передавать Authorization: Bearer <token>, иначе возвращается 401

Endpoint отключен по умолчанию. Включайте его, только когда метрики кто-то собирает, и закрывайте порт на сетевом уровне так же, как для /healthz.

Значение для auth_token можно получить командой openssl rand -hex 32. Пример настройки сбора в Prometheus:

scrape_configs:
  - job_name: web
    scheme: https
    metrics_path: /metrics
    bearer_token_file: /etc/prometheus/incidentrelay.token
    static_configs:
      - targets:
          - incidentrelay.example.com

Метрики:

МетрикаТипОписание
incidentrelay_http_requests_totalcounterОбработанные HTTP-запросы, метки method и status
incidentrelay_http_request_duration_secondshistogramЗадержка обработки запросов, метка method
incidentrelay_database_upgauge1, если база ответила на SELECT 1 в момент сбора, иначе 0
incidentrelay_migrations_pendinggaugeЧисло файлов миграций, которые еще не применены; отсутствует, пока состояние миграций неизвестно
incidentrelay_build_infogaugeВерсия запущенного сервиса, метка version, значение всегда 1
incidentrelay_alerts_received_totalcounterАлерты, принятые через integration API, метка source
incidentrelay_alert_group_actions_totalcounterПереходы групп алертов, метка action: created, acknowledged, resolved, reopened
incidentrelay_user_notification_deliveries_recentgaugeДоставки пользовательских уведомлений, обновленные за последние 24 часа, метки method и status
incidentrelay_alert_notification_errors_recentgaugeДоставки уведомлений алертов, завершившиеся ошибкой, обновленные за последние 24 часа, метка provider
incidentrelay_scheduler_last_run_timestamp_secondsgaugeUnix-время последнего heartbeat планировщика, 0, если он еще не запускался
incidentrelay_worker_last_seen_timestamp_secondsgaugeПоследний успешный heartbeat цикла worker; метка worker: scheduler, telegram, slack
incidentrelay_user_notification_queue_depthgaugeПользовательские уведомления, уже ожидающие обработки или находящиеся в обработке; метка state: due, processing
incidentrelay_user_notification_queue_oldest_age_secondsgaugeВозраст самого старого элемента очереди пользовательских уведомлений; метка state: due, processing
incidentrelay_orchestration_pending_eventsgaugeОтложенные события оркестрации; метка status: pending, activating, failed
incidentrelay_orchestration_oldest_due_age_secondsgaugeВозраст самого старого отложенного события, для которого уже наступило время активации/retry

incidentrelay_database_up и incidentrelay_migrations_pending вычисляются в момент сбора и повторяют проверки /readyz. /metrics продолжает отвечать, когда база данных недоступна, поэтому обе метрики остаются видимыми во время сбоя. Пока состояние миграций прочитать нельзя (база недоступна или проверка не выполнилась), сэмпл incidentrelay_migrations_pending отсутствует, а не равен 0 — метрика отдается только тогда, когда ее значение действительно известно. Заведите алерт на incidentrelay_database_up = 0 и не полагайтесь только на число отложенных миграций.

Подсчет запросов активен только при enabled = true. После изменения настроек metrics перезапустите веб-сервис, а также планировщик и воркеры — они подхватывают настройку при старте. /metrics отдает только веб-сервис; планировщик и остальные воркеры только записывают в него события.

Обычно IncidentRelay работает несколькими процессами за одной точкой сбора: несколько Gunicorn-воркеров плюс отдельные демоны планировщика и Telegram/Slack-воркеров. Чтобы один сбор /metrics покрывал их все, каждый процесс IncidentRelay записывает свои счетчики в один общий каталог, заданный переменной окружения PROMETHEUS_MULTIPROC_DIR, а веб-воркеры при сборе объединяют файлы всех процессов. В готовых поставках это уже настроено: systemd-юниты используют общий каталог /run/incidentrelay/metrics, поэтому сбор покрывает все юниты хоста — веб-воркеры, планировщик и чат-воркеры. Без переменной — одиночный процесс в development-запуске — счетчики покрывают только этот один процесс.

Файлы счетчиков привязаны к PID процессов, поэтому каталог PROMETHEUS_MULTIPROC_DIR можно разделять только процессам, которые видят одни и те же PID: на одном хосте или внутри одного контейнера. Никогда не указывайте контейнерам один и тот же каталог — независимые PID-пространства могут переиспользовать одни и те же PID и портить файлы друг друга. Поэтому Docker-образ дает каждому сервисному контейнеру собственный каталог внутри /var/lib/incidentrelay/metrics/; сбор /metrics в контейнерной поставке агрегирует воркеров веб-контейнера, а переходы от планировщика и чат-воркеров попадают в их собственные каталоги и в нем не видны. Чтобы объединить их, понадобился бы механизм агрегации через границы контейнеров, которого в этой функциональности нет.

Если указываете свой путь в PROMETHEUS_MULTIPROC_DIR, оставьте его процессам одного хоста или одного контейнера; каталог должен существовать и быть доступен для записи до старта процессов, при выключенном [metrics] каталог вообще не затрагивается, так что нерабочий каталог никогда не блокирует выключенное развертывание. Файлы live-гаугов завершившихся процессов удаляются при запуске следующего процесса IncidentRelay. Файлы счетчиков и гистограмм умерших процессов намеренно сохраняются: удаление одного из них уменьшает объединенный счетчик на долю умершего процесса, а Prometheus читает это как сброс счетчика и искажает rate() и increase(). Устаревшие файлы счетчиков продолжают участвовать в агрегации, пока каталог не будет очищен при полном передеплое; их количество ограничено числом разных PID, которые каталог когда-либо видел. Очистка гаугов определяет живость по PID, поэтому переиспользованный PID сохраняет файл гауга умершего процесса, пока не завершится процесс, который теперь владеет этим PID.

Гаужи, считаемые из базы (incidentrelay_database_up, incidentrelay_migrations_pending, incidentrelay_user_notification_deliveries_recent, incidentrelay_alert_notification_errors_recent, incidentrelay_scheduler_last_run_timestamp_seconds, incidentrelay_build_info), вычисляются один раз за сбор, поэтому их значения не зависят от числа процессов.

incidentrelay_user_notification_deliveries_recent, incidentrelay_alert_notification_errors_recent и incidentrelay_scheduler_last_run_timestamp_seconds пересчитываются из базы в момент сбора, поэтому работают между процессами. Обе метрики доставок учитывают строки, обновленные за последние 24 часа: строки доставок меняются на месте (pending переходит в sent или failed, приходят новые ошибки провайдеров), поэтому окно идет по updated_at, а не по created_at, и сбор никогда не сканирует всю историю доставок. Когда база недоступна, они исчезают из выдачи, а heartbeat равен 0; причину показывает incidentrelay_database_up = 0. Для heartbeat нужен работающий воркер планировщика; сама heartbeat-job запускается только при включенном [metrics].

incidentrelay_worker_last_seen_timestamp_seconds хранится в БД, поэтому работает между systemd-сервисами и отдельными Docker/Kubernetes-контейнерами. Scheduler также остается доступен под совместимым именем incidentrelay_scheduler_last_run_timestamp_seconds. Telegram и Slack обновляют timestamp после успешной итерации worker; alert следует настраивать только для тех worker, которые действительно запущены в deployment.

Гейджи очереди пользовательских уведомлений показывают текущий backlog, а не историю. state="due" считает только pending-доставки, у которых уже наступил scheduled_at, поэтому намеренно отложенные уведомления не выглядят зависшими. state="processing" считает захваченные доставки, а возраст измеряется от последнего обновления состояния.

incidentrelay_orchestration_pending_events показывает текущее состояние отложенных событий. failed означает, что автоматические попытки активации исчерпаны и событие требует внимания. incidentrelay_orchestration_oldest_due_age_seconds учитывает только pending-события, у которых уже наступило время активации/retry; будущие pause-события возраст не увеличивают.

Дашборд Grafana#

Когда Prometheus хотя бы один раз успешно соберёт метрики веб-сервиса IR, загрузите tools/grafana/incidentrelay-overview.json через Dashboards → New → Import в Grafana. При импорте укажите источник данных Prometheus, затем выберите IR scrape job и Web target на дашборде. В настройках источника задайте фактический интервал сбора Prometheus: от него зависит окно расчёта скорости.

Для каждой установки IR со своей БД используйте отдельный job. Настройте сбор с каждой веб-реплики отдельно: дашборд суммирует скорость запросов и событий, но не складывает копии одной очереди из общей БД. Результаты доставки показаны за предыдущие 24 часа в каждой точке графика, независимо от выбранного периода. Отсутствие данных не означает ноль: при сбое БД может исчезнуть число миграций, а линия необязательного воркера появится только после первого heartbeat. В Docker и Kubernetes счётчики отдельных контейнеров планировщика и воркеров могут не попасть в метрики веб-сервиса; их очереди по-прежнему видны по данным БД.

Настройки планировщика#

Процесс планировщика проверяет напоминания, эскалации и периодические задания.

Планировщик обновляет heartbeat каждые heartbeat_interval_seconds (по умолчанию 30, секция [scheduler]); метрика incidentrelay_scheduler_last_run_timestamp_seconds в /metrics показывает, как давно он запускался.

Интервал пробуждения планировщика отличается от интервалов напоминаний ротаций. Интервалы напоминаний ротаций настраиваются для каждой ротации отдельно:

0 disables reminders for that rotation
>= 60 sends reminders at that interval in seconds
1..59 invalid

Не используйте глобальную настройку reminder-after как запасной вариант во время выполнения, когда ротации требуют явного интервала.

Журналирование#

Если включено журналирование в файл, используйте путь с правами на запись:

[main]
log_level = INFO
log_file = /var/log/incidentrelay/incidentrelay.log

Для systemd и контейнеров проверяйте также журнал или логи контейнера.

Экспериментальный приём Change Intelligence#

Все настройки Change Intelligence действуют для всей установки. Наследование для будущих групповых параметров описано в архитектуре системных настроек.

Глобальный администратор управляет переключателями Приём Change Events и Фоновая обработка изменений в разделе Администрирование → Системные настройки или через GET и PATCH на /api/admin/system-settings. Чтобы приостановить обработку, достаточно передать {"change_worker_enabled": false}. Для приёма используется поле change_intake_enabled. На новой установке приём выключен, фоновая обработка включена. После включения приёма авторизованные интеграции могут отправлять события на POST /api/change-events.

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

Расширенные настройки Change Intelligence#

В разделе Администрирование → Системные настройки → Расширенные настройки измените нужные числа и нажмите Сохранить. API принимает те же целые числа через частичный PATCH /api/admin/system-settings. База данных хранит значения для всех процессов IR. Если вы задавали свои лимиты в тестовой версии 2.5 через файл или окружение, внесите их здесь после миграции.

Поле APIНазначениеПо умолчаниюДиапазон
change_max_future_secondsДопустимое опережение времени события (секунды)300≥ 0
change_events_per_minuteНовых событий на интеграцию в минуту600≥ 1
change_events_per_changeСобытий на одно изменение10001–10000
change_worker_interval_secondsИнтервал запуска обработчика (секунды)5≥ 1
change_worker_jobs_per_tickЗаданий за один запуск201–100
change_worker_batch_sizeЗаписей в одной порции1001–1000
change_worker_lease_secondsСрок аренды задания (секунды)60≥ 10
change_worker_max_attemptsМаксимум попыток на задание8≥ 1
change_worker_retry_base_secondsНачальная задержка повтора (секунды)5≥ 1
change_worker_retry_max_secondsМаксимальная задержка повтора (секунды)300≥ 1
change_pending_ttl_secondsСрок ожидания привязки сервиса (секунды)604800≥ 60
change_pending_poll_secondsИнтервал проверки ожидающих привязок (секунды)60≥ 5

Общий верхний предел целого значения — 2 147 483 647. Начальная задержка повтора должна укладываться в максимальную. Можно изменить обе одним запросом. Квота интеграции охватывает все её Sources и токены за скользящую минуту. Точные повторы событий сохраняют прежний результат и не расходуют квоту.

Каждый экземпляр планировщика проверяет интервал обработчика раз в пять секунд, в том числе при выключенной обработке. При смене интервала следующий запуск отсчитывается от момента применения. Начатая порция завершается со своим лимитом. Уже записанные сроки истечения привязок, аренды и повторов сохраняются. Новая настройка действует при следующем назначении срока или продлении аренды.

Тело ограничено 256 KiB до разбора, суммарно допускается 100 ссылок на сервисы, details — 64 KiB, 10 уровней вложенности и 2000 узлов. Весь payload ограничен 15 уровнями и 5000 узлами. Повторные JSON-ключи, NaN/Infinity, NUL и некорректный Unicode отклоняются. Время требует часового пояса и максимум шести знаков долей секунды. Title ограничен 500 символами, description — 10000, URL — 2048; разрешены только HTTP(S) URL без credentials. Передачу тела ограничивайте существующими таймаутами WSGI/reverse proxy.

201 подтверждает сохранение, 200 — точный повтор. Конфликт event_id/content или неизменяемой идентичности операции даёт 409. После 429 повторяйте через 60 секунд, после 503 — минимум через секунду, с тем же event_id и содержимым. На PostgreSQL таймауты блокировки/SQL равны 2/5 секундам на попытку; временные ошибки БД повторяются максимум три раза. Остальные ошибки записи возвращают 500; ошибка до commit откатывает транзакцию. При потере соединения во время commit результат может быть неизвестен: повтор с той же идентичностью и содержимым безопасно вернёт сохранённое событие. Payload не включается в ошибки и журналы. Worker этапа 5 обрабатывает pending-ссылки; исходные события не удаляются. Сохранённые идентификаторы доступны для повторов, пока хранятся. Контракты порядка, grants и namespace описаны в OpenAPI и архитектуре.

Worker Change Intelligence#

Обработчик очереди работает независимо от приёма событий. Далее приведены значения по умолчанию.

За один запуск начинается до 20 заданий; после 10 секунд новые задания не берутся. Ссылки и discovery обрабатываются порциями по 100 записей (диапазон 1–1000), лимит заданий — 1–100. Аренда действует 60 секунд (минимум 10), при расчёте ссылок продлевается каждые десять записей. При сохранении под блокировками проверяются токен аренды, поколение, срок и ревизии Change/auth/graph; перед подтверждением задания проверка повторяется. PostgreSQL использует SKIP LOCKED, SQLite резервирует запись до чтений. Старый worker не может сохранить результат или изменить повторные попытки нового владельца.

Успешная порция сохраняет курсор и обнуляет бюджет технических ошибок. Временные ошибки БД повторяются с экспоненциальной задержкой и случайным разбросом от половины до полного значения; максимум задержки — 300 секунд. Восемь неудачных попыток, включая падения с истёкшей арендой, исчерпывают бюджет. Неожиданная ошибка сразу переводит задание в dead; сохраняется безопасная категория ошибки. Периодический обход не перезапускает dead-задания. Новое принятое событие или аудируемая команда оператора может создать новое поколение.

TTL pending-ссылки — семь дней с момента приёма (минимум 60 секунд), а не с occurred_at отправителя. Для старых pending без expires_at используется исходный created_at. Разрешённый Service ID остаётся закреплённым навсегда. Недоступный namespace/Service даёт invalid, отсутствие текущих прав — denied, истечение окна — expired. Повтор оператором или новое принятое событие с той же ссылкой заново проверяет текущие права и закреплённую идентичность. Точный повтор event_id не меняет состояние и TTL. Неизвестный сервис проверяется раз в 60 секунд (минимум 5); ожидание его появления не считается технической ошибкой. Отзыв или истечение токена не отменяет принятую работу: используются текущие интеграция, Source и grants.

Изменения каталога и зависимостей атомарно повышают graph revision и запрашивают ограниченный по порциям обход сохранённых Change. Изменения прав обходят Change затронутой интеграции. Верхняя граница и курсор каждого обхода сохраняются. Периодическая страховочная сверка читает только индексированные pending-ссылки, а не всю историю Change. Она восстанавливает пропущенную работу, не сбрасывая активный обход и не оживляя dead-задания. Полный пересчёт может занимать несколько порций: актуальный полный результат требует совпадения input stamp, отсутствия курсора оставшихся порций и claimed_generation=requested_generation. Задание может быть done или pending до следующей проверки отсутствующего сервиса; новый запрос или незавершённая порция не считаются полным проходом. До завершения прохода отдельные канонические связи могут иметь предыдущую ревизию Change.

Глобальный администратор использует GET /api/admin/change-integrations/jobs; администратор группы — GET /api/admin/change-integrations/{integration_id}/jobs для принадлежащей группе интеграции. Нужен JWT. Возвращаются только метаданные очереди, есть фильтр state и курсор after, по 50 записей. Для повтора отправьте POST на соответствующий /jobs/{job_id}/retry с телом {"expected_generation": <requested_generation>}. Устаревшее поколение даёт 409. Повтор записывается в аудит и обновляет TTL заблокированных неразрешённых ссылок; исходные идентификаторы и уже разрешённые Service ID сохраняются. Grants всегда проверяются заново.

Метрики: incidentrelay_change_worker_results_total содержит фиксированные категории захвата/результата; incidentrelay_change_jobs, incidentrelay_change_queue_oldest_due_age_seconds, incidentrelay_change_references, incidentrelay_change_dead_jobs показывают размер очереди, возраст и ошибки без меток source/Team/Service. Этап 7 включает impact, корреляцию и discovery допустимых эпизодов. Этап 9 включает безопасную публикацию Service Timeline через тот же worker.

Чтобы приостановить весь поток, выключите оба переключателя в разделе системных настроек. Сохраняйте строки и курсоры: после включения истёкшие аренды перехватит новый worker. Этап 5 не удаляет события, задания и digest идентичности; повторы доступны, пока хранится история. Retention/tombstones остаются для следующих этапов; горизонт автопоиска описан ниже.

Changes Inbox и API чтения#

Откройте Операции → Изменения. Поиск, фильтры и страница сохраняются в URL, карточка имеет прямую ссылку по UUID. Общий фильтр Team отбирает владельца или доступный связанный сервис. Фильтры status/source/environment относятся только к полным карточкам владельца и исключают ограниченные межкомандные карточки.

Владелец видит конфликт итогов, диагностику связывания сервисов и историю событий. Читателю связанного сервиса доступна ограниченная карточка без исходного названия, source, инициатора, внешних ID, URL и payload. Устаревшие или отозванные связи скрываются до перепроверки. Кнопка обновления перечитывает состояние; при ошибке старые данные очищаются и доступен повтор. Связывание сервисов и автокорреляция — отдельные шаги worker. Ручной review и связи Incident доступны в Change Details. Related Changes на страницах AlertGroup/Incident и Timeline относятся к этапу 9.

API требует JWT пользователя или его личный токен с changes:read, даже при необязательной глобальной авторизации. Ограничения Group/Team токена сохраняются; /api/services/{id}/changes дополнительно требует services:read. Машинные токены не могут читать Changes. Ответы имеют Cache-Control: no-store; отсутствующий и недоступный ресурс получают одинаковый 404.

curl --fail-with-body "$IR_URL/api/changes?kind=deployment&page_size=25" \
  -H "Authorization: Bearer $PERSONAL_TOKEN"
curl --fail-with-body "$IR_URL/api/changes/$CHANGE_UID/events?page=1" \
  -H "Authorization: Bearer $PERSONAL_TOKEN"

История events доступна владельцу. /services выдаёт доступные канонические связи и владельцу — отдельно пагинируемые исходные ссылки. Обе коллекции используют page/page_size (1–100). Ограниченная карточка содержит до пяти связей; остальные доступны через /services. SQL-фильтрация выполняется до подсчёта и пагинации. Для фильтра сервиса используйте service_id либо service_slug с одним namespace: team_id или team_slug. scope_team_id задаёт контекст Team, owner_team_id — доступного владельца. occurred_from/occurred_to включают границы и требуют ISO время с часовым поясом. Неизвестные или повторные параметры дают 400.

На внутреннем стенде с включённым приёмом сначала создайте интеграцию/Source, grant changed на целевой сервис и машинный токен. Замените ID, имя Source и время события значениями своего стенда:

curl --fail-with-body "$IR_URL/api/change-events" \
  -H "Authorization: Bearer $CHANGE_TOKEN" -H "Content-Type: application/json" \
  --data '{"schema_version":1,"event_id":"deploy-42-started","change_id":"deploy-42","owner_team_id":1,"source":"deploy","kind":"deployment","event_type":"change.started","occurred_at":"2026-11-02T12:00:00Z","title":"Deploy checkout 42","changed_service_ids":[1]}'

После сетевой ошибки повторите тот же event_id и payload: точный повтор даёт 200. Завершение использует прежний change_id, новый event_id, тип события и время отправителя. source_sequence нужен только Source с режимом sequence. Публичный приём остаётся выключенным до сквозной приёмки этапа 10.

Автоматические предложения Changes#

В редакторе Service включите автоматические предложения для сервисов, алерты которых нужно сопоставлять с изменениями. По умолчанию настройка выключена, включая обновление. POST/PUT Service принимают change_correlation_enabled и change_correlation_exclusions; при PUT пропущенные настройки сохраняются, [] очищает исключения.

Пример: [{"source":"heartbeat"},{"labels":{"kind":"synthetic"}}]. Source — источник алерта. Все условия одного правила должны точно совпасть у одного ребёнка. Совпадение любого правила исключает ребёнка; эпизод участвует, если остаётся хотя бы один неисключённый ребёнок, включая уже resolved детей этого цикла. Применяются обычные права Service; изменение настройки и запись аудита атомарны.

Горизонт истории — семь дней, при этом более старые running Changes остаются допустимыми. Окно после операции — два часа. Контекст старых групп/эпизодов не восстанавливается. Этап 7 сохраняет предложения potential_cause без изменения статусов и уведомлений; review доступен в Change Details; связи также доступны на страницах AlertGroup и Incident. Публичный приём выключен до этапа 10. Лимиты движка: глубина 5, 200 связей/строк влияния, 1000 рёбер и пять секунд на расчёт; настройки batch/lease/retry worker продолжают действовать. Превышение лимита графа записывает limit_exceeded в задание.

При откате на версию без поддержки новых связей в retention также выключите очистку истории алертов ([retention] alert_days=0). Добавленные таблицы и evidence сохраняйте.

Ручные связи изменений#

В Change Details можно подтвердить или отклонить предложение, вручную указать context/mitigation/причину для существующего эпизода и связать Change с Incident. Нужны доступ к Change, роль responder на целевом ресурсе и пояснение решения. Ручное связывание доступно независимо от настройки автокорреляции и её временного окна. Старые AlertGroup без эпизодов не создаются в списке выбора; для них доступна прямая связь с Incident.

При конфликте версий закройте диалог и обновите данные. Удалённую связь Incident можно восстановить из меню действий. Состояния алерта/инцидента и уведомления эти операции не меняют. Перед запуском обновлённого приложения примените миграции, включая 20261104010000_change_reviews. Публичный приём остаётся выключенным до этапа 10.

Перед запуском обновлённого приложения и worker примените 20261104020000_change_service_timeline. Миграция сохраняет прежние Service events и ставит в очередь перепроверку принятых Changes; эпизоды старых алертов не создаются. Ошибки публикации timeline используют существующие retry/backoff/dead-letter; повторный запуск доступен администраторам интеграции.

В деталях алерта → Related Changes можно выбрать последний или исторический эпизод и проверить/привязать Change именно к нему. Incident workspace предоставляет те же действия с ролью связи, её изменением, удалением и восстановлением. Ручные связи доступны и при выключенной автокорреляции. Для старой группы без эпизода выводится пояснение; эпизод появится только при настоящем reopen.

Service Timeline ведёт на авторизованную страницу Change. В сохранённой проекции есть только UUID изменения, тип, связь и время события, даже для владельца. Косвенное влияние отмечено отдельно. История сервиса перечитывается при открытии; устаревшие производные связи скрываются после изменения доступа или графа. Публичный приём остаётся выключенным до приёмки этапа 10.