События проекта и реестр событий

Два экрана отвечают на два разных вопроса. События — «что реально пришло в проект прямо сейчас». Реестр событий — «а что вообще должно приходить и с какими полями». Первый показывает факты, второй задаёт контракт, по которому эти факты проверяются на приёме.

Держите оба открытыми, когда меняете разметку: реестр говорит, каким должно быть событие, экран событий — каким оно пришло.

Экран событий

Данные и сбор → События. Один хронологический список, а не вкладки: история и живой поток попадают в одну таблицу.

Что в таблице

Шесть столбцов: время, событие, посетитель, URL, устройство, страна.

Столбец «Посетитель» — ссылка. У опознанного человека показывается его идентификатор, у анонимного — «Аноним» и короткий хвост анонимного идентификатора; полное значение видно во всплывающей подсказке. Ссылка ведёт в карточку человека и переносит туда выбранный период.

Клик по строке открывает панель с полным JSON события, включая props. Это единственное место в продукте, где видно событие целиком, ровно как оно сохранено.

Фильтры

• Событие. Кнопка «+ Добавить событие» добавляет ещё одну строку выбора — число строк не ограничено, условия складываются по «или». Значение «Любое событие» сбрасывает выбор.
• user_id и anon_id — точное совпадение. Оба поля с задержкой: запрос уходит через 400 мс после того, как вы перестали печатать.
• Период — по умолчанию последние 30 дней. Календарные даты разворачиваются в интервал по UTC от 00:00:00 первой даты до 23:59:59 последней.

Кнопка «Сбросить» возвращает фильтры к состоянию по умолчанию.

История листается непрозрачным курсором по 50 событий на страницу: следующая порция подгружается сама, когда последняя строка попадает в область просмотра. Больше 100 событий за один запрос API не отдаёт в любом случае.

Живой поток

Живой режим выключен по умолчанию — пилюля в заголовке показывает «Лайф выключен». Переключатель поднимает подписку на поток событий, и рядом появляется состояние соединения: «Стрим подключен», «Подключение…», «Поллинг» или «На паузе».

Что важно знать про поток:

• Кольцевой буфер на 500 событий. Подпись «В буфере: N (макс. 500)»; событие номер 501 вытесняет самое старое. Буфер живёт в браузере и очищается при переключении проекта.
• Пауза. Кнопка «Пауза» останавливает пополнение таблицы, но не поток: пришедшее за это время копится отдельно, и кнопка становится «Продолжить (+N)».
• Запасной путь. После трёх неудачных попыток подключения подряд интерфейс переходит на периодический опрос раз в 3 секунды — состояние «Поллинг». Данные продолжают идти, задержка растёт.
• Прореживание. Выше 20 сообщений в секунду сервер прореживает поток. Это инструмент наблюдения, а не учёта: считать события по живому потоку нельзя, для чисел есть отчёты.

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

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

Реестр событий

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

Список: событие, владелец, источник, статус, текущая версия схемы и объём за 24 часа и 7 дней. Фильтры — по статусу (Черновик / Активно / Устарело) и по источнику (Не указан / Browser / Server / Import / System). Страница — 50 записей, листается кнопками «← Назад» и «Далее →».

Контракт события

Кнопка «Зарегистрировать событие» открывает форму контракта. Что в неё входит:

Поле	Ограничение
Event name	правило ^[a-z0-9_.]{1,128}$, нельзя начинать с pp.
Название	до 200 символов
Команда-владелец	до 200 символов
Описание	до 4000 символов
Источник	Не указан, Browser, Server, Import, System
Статус	Черновик, Активно, Устарело
Ожидаемые поля	JSON-массив, не более 64 полей

Каждое ожидаемое поле описывается тремя обязательными вещами: name (до 64 символов, уникальное в схеме), type — один из string, number, boolean, object, array, null — и classification:

• normal — обычное поле;
• potential_pii — поле, в которое персональные данные могут попасть случайно;
• forbidden — поле, которого в событии быть не должно.

Дополнительно можно указать required, description и safe_example. Поле с классификацией forbidden не может быть обязательным и не может иметь примера — форма отклонит такую схему.

Встроенные события pp.* — контракт платформы. Их схему выпускает ActionPulse, кнопок «Изменить метаданные» и «Новая версия» у них нет ни у одной роли, и пространство имён pp. зарезервировано: своё событие так назвать нельзя.

Версии схемы

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

Схема правится только добавлением новой версии. Кнопка «Новая версия» открывает редактор с подсказкой: «Новая версия неизменяема после сохранения. Допустимо не более 64 полей». Сохранённая версия больше не меняется никогда — это и есть смысл версионирования.

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

Практическое следствие: не переименовывайте поля и не меняйте их тип «на месте». Добавьте новую версию — старые события останутся объяснимыми.

Бизнес-определения

На том же экране, над списком, живёт карточка «Бизнес-определения». В ней выбирается событие полезной активности: уникальный посетитель, совершивший именно это событие, считается активным пользователем в DAU, WAU и MAU и в шаблонах SQL-запросов.

В выбор попадают только события со статусом «Активно» и заданным названием. Статус определения — «Не настроено», «Настроено» или «Требует внимания»; последнее означает, что выбранное событие удалено, перестало быть активным или потеряло название. Пока определение не настроено, активность считается технически: подходит любое событие, и обзор проекта об этом предупреждает.

Режимы проверки

Селектор «Режим проверки» вверху экрана реестра задаёт, что происходит с событием, которое не совпало со своим контрактом. Новые проекты начинают с режима «Мониторинг».

Режим	Что делает
Выключена	схема клиентских событий не проверяется, результат проверки — «Не проверено»
Мониторинг	нарушения записываются, событие принимается
Строгая проверка	элемент с нарушением уровня ошибки отклоняется

Переключение в строгую проверку требует подтверждения: в диалоге нужно ввести слово ENFORCE, до этого кнопка подтверждения заблокирована. Текст диалога объясняет границу: «Enforce отклоняет только нарушившие контракт элементы batch. Перед включением проверьте monitor-нарушения». Остальные события того же запроса будут приняты.

Два правила действуют независимо от режима:

• Зарезервированные имена. Событие с именем из пространства pp.* проверяется как в строгом режиме всегда. Подделанное pp.-событие отклоняется даже при выключенной проверке — иначе чужое событие попало бы в отчёты как собранное платформой.
• Запрещённые поля. Поле с классификацией forbidden удаляется из сохранённого события, а поле potential_pii, значение которого совпало с шаблоном персональных данных, заменяется на "[redacted]". Это происходит и в режиме мониторинга.

Менять режим может администратор или владелец организации; регистрировать события и создавать версии схемы — аналитик и выше.

Откуда берутся нарушения

Проверка идёт на приёме события, до записи. Результат — «Валидно», «Нарушение» или «Не проверено» — сохраняется вместе с событием и виден на вкладке «Нарушения» экрана проверки интеграции.

Десять кодов, их уровень и последствие:

Код	Когда	Уровень	В строгом режиме
event_unregistered	события нет в реестре	ошибка	отклоняется
reserved_event	попытка занять имя pp.*	ошибка	отклоняется в любом режиме
schema_version_unknown	указана версия схемы, которой нет	ошибка	отклоняется
required_property_missing	нет обязательного поля	ошибка	отклоняется
property_type_mismatch	тип поля не совпал со схемой или значение вне заявленных ограничений	ошибка	отклоняется
unknown_property	поля нет в схеме версии	ошибка	отклоняется
forbidden_property	пришло запрещённое поле	ошибка	отклоняется, значение не сохраняется
event_deprecated	событие помечено «Устарело»	предупреждение	принимается
registry_unavailable	реестр недоступен в момент проверки	ошибка	запрос завершается ошибкой, а не тихой потерей
violations_truncated	нарушений оказалось больше, чем помещается	предупреждение	принимается

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

Обратите внимание на асимметрию: event_deprecated — предупреждение, поэтому устаревшее событие продолжает приниматься даже в строгом режиме. Это способ выводить старую разметку из обращения, не ломая приём. Построители отчётов при выборе такого события показывают отдельное предупреждение «Устаревшие события».

Сигналы здоровья разметки

Отдельного экрана «состояние интеграции» в продукте нет — есть четыре рабочих источника сигнала, и у каждого своя задача.

Объём в реестре. Столбец «24ч / 7д» в списке событий реестра. Самый быстрый способ увидеть, что событие перестало приходить или, наоборот, стало приходить на порядок чаще.

Вкладка «Нарушения». Полная история результатов проверки за период до 31 дня с фильтрами по коду и решению. Начинать разбор нужно отсюда.

Оповещение «Нет событий». Срабатывает, если события не приходят заданное число минут. Настраивается в Мониторинг → Оповещения и стоит того, чтобы включить его сразу после подключения: это самый дешёвый способ узнать, что разметка сломалась при релизе.

Оповещение «Качество данных». Считает детерминированные сигналы реестра за окно от 15 минут до 7 дней и срабатывает, если появились сигналы уровня warning или critical. Окно сравнивается с непосредственно предшествующим окном той же длины. Пять типов сигналов:

Сигнал	Условие warning	Условие critical
Доля нарушений	5 % попыток	20 % попыток
Всплеск объёма	×2 к базовому темпу	×4
Падение объёма	×0,5 к базовому темпу	×0,1
Дрейф набора свойств	набор полей события изменился	—
События остановились	поток по событию прекратился	—

Сигналы по темпу требуют не менее 100 попыток в базовом окне, сигнал об остановке — не менее 50; при меньшей выборке продукт честно отвечает «Недостаточно данных» вместо догадки. Никаких моделей и предсказаний здесь нет — только фиксированные правила.

Что делать с нарушением

1. Откройте вкладку «Нарушения» и отфильтруйте по коду. Один код почти всегда означает одну причину.
2. event_unregistered — событие отправляется, но контракта нет. Зарегистрируйте его: в реестре можно начать регистрацию прямо с наблюдаемого имени.
3. unknown_property и required_property_missing — код и схема разошлись. Решите, кто прав. Если прав код, добавьте новую версию схемы; если права схема, поправьте отправку.
4. property_type_mismatch — самый частый случай: число уехало в строку. Посмотрите наблюдаемую форму данных на вкладке «История событий» — там видны имена полей и их типы JSON без значений — и сравните с ожидаемыми полями версии схемы.
5. forbidden_property — поле не просто отклонено, его значение не сохранено. Уберите его на стороне отправителя: сервер не должен получать то, чего не должен хранить.
6. reserved_event — переименуйте событие. Пространство pp. занято платформой.
7. Проверьте результат живым потоком: отправьте событие из нового кода и убедитесь, что в поле «Результат» появилось «Валидно».

Частая ошибка планирования: включить строгую проверку до того, как разобраны нарушения мониторинга. Тогда релиз, который «просто добавил одно поле», перестанет сохранять события целиком. Сначала пустая вкладка «Нарушения» — потом ENFORCE.

Технические подробности запросов — в разделах API Registry и Events.