Определяет контролируемую таксономию событий с бизнес-событиями, стабильными идентификаторами, типизированными свойствами, границами контекста, версионированием, целью конфиденциальности и ответственностью за качество данных для согласованного измерения.
Статус пакета: справочный контекст готов к проверке человеком. Контракт и тестовые сценарии завершены, но не заявляется, что внедрение, принявшее этот стандарт, прошло их.
Решение
Именуйте события как бизнес-события в прошедшем времени и отделяйте их от изменяемой интерпретации. Регистрируйте каждое событие и свойство до запуска в производство, используйте общий контекст только для действительно универсальных полей и версионируйте семантически несовместимые изменения.
Область применения
- Именование, семантика события, производитель, субъект, идентичность события, время, контекст, свойства, перечисления, версии, цель, класс конфиденциальности, владение и качество.
- События продуктовой и операционной аналитики, общие для производителей и потребителей.
- Реестр, управляющий валидацией и документацией.
Вне этого блока
- Определения метрик, производные на более поздних этапах, или копирование названий элементов UI в постоянную семантику событий.
- Включение всех доступных атрибутов сущности в каждое событие.
Контракт
- Каждое событие представляет одно завершённое или зафиксированное событие и указывает производителя, триггер, субъект, роль актёра, если разрешено, и семантику успеха/неудачи.
- Идентификатор события уникален для каждого события; повторные попытки сохраняют его, а разные события используют разные идентификаторы.
- Время события и время получения разделены; временные метки используют однозначный стандартный момент времени.
- Свойства имеют тип, допустимые значения, значение null/отсутствия, единицу измерения, класс конфиденциальности, цель и владельца.
- Идентификаторы сущностей стабильны и псевдонимны, если аналитика не требует прямой идентификации.
- Семантически или типово несовместимые изменения создают новую версию события; добавочные необязательные поля следуют политике совместимости.
Рекомендации по реализации
- Используйте общий конверт и схему полезной нагрузки с поддержкой реестра.
- Храните окружение, релиз, производителя, версию схемы, профиль согласия/цели и маркер тестового трафика в контролируемом контексте.
- Валидируйте на CI производителя и при приёме; помещайте несовместимые полезные нагрузки в карантин, а не принуждайте к корректировке.
- Определите канонические примеры и контрпримеры для неоднозначных событий.
Обработка ошибок и меры предосторожности
- Неизвестный тип события или обязательное свойство приводит к ошибке валидации и помещению в карантин.
- Если результат события неизвестен, используйте явное состояние или пропустите отправку согласно контракту; никогда не устанавливайте успех по умолчанию.
- При случайном повторном использовании идентификатора сохраняйте доказательства и корректируйте последующие подсчёты через версионированный ремонт.
Проверка и эксплуатация
- Измеряйте отказы схемы, неизвестные перечисления, дублирование ID событий, позднее поступление, отсутствие свойства, покрытие версий производителя и разрывы в объёмах событий.
- Назначайте владельца и дату устаревания каждой версии события.
- Сверяйте критические подсчёты событий с операционными источниками.
Примеры, похожие на исполняемые, в этом пакете являются фикстурами и контрактами приёмки. Запустите
python tools/validate.py из корня коллекции для проверки структуры пакета и метаданных; затем
реализуйте и выполните сценарии в целевом репозитории.
Предположения при внедрении
- Имена и числовые значения в
example.yaml— это профиль внедрения, а не универсальные значения по умолчанию. - Команда, внедряющая, должна сопоставить актёров, классы данных, словарь ошибок и владение со своей системой.