Управление контекстными параметрами и типами участников в репозитории метрик

Контекстные параметры и типы участников можно описать не в интерфейсе, а в YAML-файлах репозитория метрик - того же git-репозитория, где лежат ваши источники и метрики. Изменения применяются после run merge. В интерфейсе Trisigma такие записи доступны только для просмотра.

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

Где находятся файлы

Файлы лежат в каталоге traffic_markup в корне репозитория метрик, рядом с каталогами sources и metrics:

ab-metrics/
  sources/
  metrics/
  traffic_markup/
    context_params.yaml
    participant_types.yaml

Чтобы получить доступ к репозиторию метрик и клонировать его, смотрите раздел Практический Workflow.

Файл	Что в нём	Обязательность
`context_params.yaml`	Контекстные параметры, корневой ключ `context_params`	Да, хотя бы один параметр
`participant_types.yaml`	Типы участников, корневой ключ `participant_types`	Нет

Без context_params.yaml или с пустым файлом синхронизация репозитория метрик останавливается. Без participant_types.yaml типы участников из репозитория не синхронизируются, уже созданные остаются как есть.

Контекстный параметр

# traffic_markup/context_params.yaml
context_params:
  - label: cart_total
    domain: Checkout
    type: float
    title: Сумма корзины
    status: active
    splitter_allocation_param: cart_total
    report_allocation_column: cart_total
    report_metric_join_column: cart_total
  - label: pickup_point_id
    domain: Delivery
    type: str
    title: Пункт выдачи
    status: active
    splitter_allocation_param: pickup_point_id
    report_allocation_column: pickup_point_id
    report_metric_join_column: pickup_point_id

Параметр	Тип	Обязательность	Пример	Описание
`label`	`string`	Да	`"cart_total"`	Технический идентификатор. Уникален среди всех контекстных параметров пространства, включая удалённые и созданные в интерфейсе
`domain`	`string`	Да	`"Checkout"`	Домен из вашего пространства. Параметр доступен только в экспериментах этого домена
`type`	`string`	Да	`"float"`	`int`, `str`, `float`, `bool`, `date` или `semver`
`title`	`string`	Да	`"Сумма корзины"`	Название в интерфейсе. Меняется в любом статусе
`status`	`string`	Да	`"active"`	`draft`, `active` или `archived`. Значения по умолчанию нет, `deleted` не принимается
`splitter_allocation_param`	`string`	Да	`"cart_total"`	Ключ, под которым приложение передаёт значение в `randomizationUnits` запроса к Splitter. Без него параметр нельзя использовать в условиях эксперимента
`report_allocation_column`	`string`	Условно	`"cart_total"`	Имя колонки с исходным значением во view. Обязательна, если по параметру описан тип участника, см. Три имени и путь до отчёта
`report_metric_join_column`	`string`	Условно	`"cart_total"`	Имя колонки с ключом связи с метриками во view. Обязательна, если по параметру описан тип участника, см. Три имени и путь до отчёта
`assignments_source_enabled`	`bool`	Нет	`true`	По умолчанию `true`. При `false` тип участника не участвует в расчёте назначений по событиям Splitter

Значения label, report_allocation_column и report_metric_join_column не должны повторяться внутри файла.

Опечатки в именах полей не вызывают ошибку

Неизвестные ключи игнорируются. Поле report_allocation_colum с опечаткой пройдёт проверку, а значение не применится. Сверяйте имена полей с таблицей выше.

Тип участника

Тип участника в YAML ссылается на контекстный параметр с тем же label. Тип данных, домен, статус и имена колонок он берёт из описания этого параметра.

# traffic_markup/participant_types.yaml
participant_types:
  - context_param: pickup_point_id
    allowed_experiment_types:
      - switchback

Параметр	Тип	Обязательность	Пример	Описание
`context_param`	`string`	Да	`"pickup_point_id"`	Label контекстного параметра из `context_params.yaml`
`allowed_experiment_types`	`list`	Нет	`[switchback]`	Типы экспериментов, в которых доступен тип участника. Если поле не указано - `regular` и `retro`. Пустой список оставляет тип недоступным
`int_id_mapping`	`object`	Нет	`{...}`	Таблица соответствия идентификаторов. См. Маппинг идентификаторов
`transform`	`object`	Нет	`{...}`	Преобразование значения перед маппингом. Работает только вместе с `int_id_mapping`

У контекстного параметра, на который ссылается тип участника, заполните все три имени: splitter_allocation_param, report_allocation_column и report_metric_join_column. Что происходит, если какого-то нет, - в разделе Три имени и путь до отчёта.

Базовые типы user и visitor создаёт платформа. В YAML их описывать не нужно: записи с этими label синхронизация пропускает.

Поле allowed_experiment_types принимает значения regular, retro, switchback, crm, holdout_analyzer, dfp, dfp_filler. Неизвестное значение останавливает синхронизацию.

Как завести новый тип участника

Новый тип участника заводится в два шага, каждый - отдельным pull request.

Добавьте контекстный параметр в context_params.yaml со всеми тремя именами: splitter_allocation_param, report_allocation_column и report_metric_join_column. Выполните run merge. После этого Trisigma создаёт для параметра колонки во view v_clickstream_ab_event.
Объявите тип участника в participant_types.yaml и в том же pull request укажите его в поле participant источников в sources.yaml. Проверка run test убеждается, что колонки из первого шага уже есть, и пропускает изменения.

Три имени и путь до отчёта

У параметра три технических имени, каждое используется на своём шаге: от запроса приложения до соединения с метриками. В примере все три различаются, чтобы было видно, где какое прописывается.

# traffic_markup/context_params.yaml
context_params:
  - label: account_id
    domain: Trisigma
    type: str
    title: Account ID
    status: active
    splitter_allocation_param: account
    report_allocation_column: account_raw
    report_metric_join_column: account_key

# traffic_markup/participant_types.yaml
participant_types:
  - context_param: account_id

Шаг	Имя в примере	Поле	Где прописывается
Запрос к Splitter	`account`	`splitter_allocation_param`	В коде приложения: `{"type": "account", "value": "acc-1042"}` в `randomizationUnits`
Колонка с исходным значением во view	`account_raw`	`report_allocation_column`	Нигде, колонку создаёт Trisigma. Значение - строка из запроса
Колонка с ключом во view	`account_key`	`report_metric_join_column`	Нигде, колонку создаёт Trisigma. Значение - ключ связи: для `int` число, для остальных типов xxHash64 от строки
Соединение с метриками	`account_id`	`label`	В `sources.yaml`: `participant: { account_id: account_hash }`, где `account_hash` - колонка источника с тем же ключом, см. Ключ связи с метриками

Колонки account_raw и account_key в свои таблицы добавлять не нужно. Если report_allocation_column и report_metric_join_column совпадают, во view создаётся одна колонка с ключом. Так устроены записи, созданные в интерфейсе: все три имени равны label.

Что происходит при разном заполнении имён:

Запись	Результат
Контекстный параметр без типа участника, задан только `splitter_allocation_param`	Работает в условиях эксперимента. Во view колонок нет
Контекстный параметр без типа участника, заданы все три имени	Работает в условиях эксперимента. Колонки появляются во view, расчёт участников их не использует. Имена колонок участвуют в проверке конфликтов
Тип участника, заданы все три имени	Splitter делит аудиторию, отчёт считает участников и метрики
Тип участника без `report_allocation_column` или `report_metric_join_column`	Splitter делит аудиторию, но тип участника не попадает в расчёт: в отчёте нет участников. Синхронизация ошибку не возвращает
Тип участника без `splitter_allocation_param`	Тип участника нельзя использовать в эксперименте

View обновляется при run merge и раз в 10 минут, если набор колонок изменился. Ручные изменения во view при обновлении теряются.

Изменения и жизненный цикл

Статус задаётся полем status. Переход применяется при run merge.

Действие в YAML	Результат
Новый параметр с `status: draft`	Черновик. В экспериментах недоступен
`draft` → `active`	Параметр доступен в новых экспериментах
`active` → `archived`	Запущенные эксперименты продолжают работать, в новых параметр недоступен
`archived` → `active`	Параметр снова доступен в новых экспериментах
`active` или `archived` → `draft`	Не поддерживается, синхронизация останавливается
Параметр удалён из файла, был `draft`	Переходит в `deleted`, label занят навсегда
Параметр удалён из файла, был `active`	Переходит в `archived`
Параметр удалён из файла, был `archived`	Не меняется

Что нельзя менять у активного параметра

У параметра в статусе active или archived меняется только title. Изменение type, domain или любой из трёх колонок проходит проверку run test, но после run merge синхронизация завершается ошибкой Modifications forbidden. Пока ошибка не исправлена, не применяются никакие изменения репозитория метрик.

Чтобы поменять тип или колонки:

Добавьте параметр с новым label и нужными настройками.
Если параметр - тип участника, опишите новый тип участника и создайте новый эксперимент на нём.
Перенастройте приложение на новый ключ в randomizationUnits.
Старый параметр переведите в archived.

Ограничения именования колонок

Ключ Splitter, колонка аллокации и колонка связи

Если report_allocation_column совпадает со splitter_allocation_param, report_metric_join_column должна совпадать с ними. Комбинация «аллокация равна ключу Splitter, колонка связи называется иначе» останавливает расчёт участников по всем экспериментам пространства, а не только по новому.

Безопасные варианты:

все три имени одинаковые, как при создании в интерфейсе;
report_allocation_column отличается от splitter_allocation_param.

Колонки всех параметров и типов участников, в том числе созданных в интерфейсе и черновиков из YAML, живут в одном view. Если две записи требуют колонку с одним именем, но с разным содержимым, view не собирается и синхронизация репозитория останавливается при run merge.

Не используйте в колонках:

служебные имена: event_date, event_timestamp, eid, is_human, business_platform, app_version, ab_event_type, abs;
колонки базовых типов: user, user_id (кроме параметра с типом int и ключом user_id), cookie, cookie_id;
имя колонки другой записи, если у неё другой тип данных или другой ключ Splitter.

Маппинг идентификаторов

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

participant_types:
  - context_param: seller
    int_id_mapping:
      table: dwh.sellers
      source_column: dwh_id
      assignment_column: ext_id

Поля объекта int_id_mapping:

Параметр	Тип	Обязательность	Пример	Описание
`table`	`string`	Да	`"dwh.sellers"`	Таблица соответствия, доступная из Trino. Проверяется при `run test`
`source_column`	`string`	Да	`"dwh_id"`	Колонка с числовым идентификатором, который становится ключом участника в отчёте
`assignment_column`	`string`	Да	`"ext_id"`	Колонка, значение которой сравнивается со значением из `report_allocation_column`

Если значение из запроса нужно привести к формату assignment_column, добавьте объект transform с полем assignment_column_transform. Это SQL-выражение с плейсхолдером {column}, например "CAST({column} AS BIGINT)". Оно применяется к значению из report_allocation_column перед сравнением.

transform без int_id_mapping

transform без int_id_mapping проходит проверку, но останавливает расчёт участников по всем экспериментам пространства. Используйте transform только вместе с int_id_mapping. Поле source_column_transform платформа не применяет.

Конфликты с записями из интерфейса

Label в интерфейсе и в репозитории делят одно пространство имён.

Если контекстный параметр с таким label уже создан в интерфейсе, параметр из YAML пропускается без ошибки в pull request.
Если тип участника с таким label уже создан в интерфейсе, run merge завершается ошибкой.
Удаление записи в интерфейсе label не освобождает. Переименуйте запись в YAML.

Синхронизация репозитория не меняет записи с источником custom_ui. Удаление параметра из YAML затрагивает только записи с источником custom_git.

Типовые сценарии

Строковый идентификатор участника

Идентификатор аккаунта содержит буквы, например acc-1042.

# traffic_markup/context_params.yaml
context_params:
  - label: account_id
    domain: Trisigma
    type: str
    title: Account ID
    status: active
    splitter_allocation_param: account_id
    report_allocation_column: account_id
    report_metric_join_column: account_id

# traffic_markup/participant_types.yaml
participant_types:
  - context_param: account_id
    allowed_experiment_types:
      - regular
      - retro

Приложение передаёт {"type": "account_id", "value": "acc-1042"} в randomizationUnits. В источнике метрик колонка участника считается формулой from_big_endian_64(xxhash64(to_utf8(account_id))), пример - в разделе Ключ связи с метриками.

Тип int для такого идентификатора не подходит: нечисловые значения превращаются в 0, и участники не попадают в расчёт.

Параметр только для условий отбора

Для условий попадания в эксперимент достаточно splitter_allocation_param. Тип участника по такому параметру не описывайте.

context_params:
  - label: in_loyalty_program
    domain: Trisigma
    type: bool
    title: In loyalty program
    status: active
    splitter_allocation_param: in_loyalty_program

Тип участника для switchback

Switchback-эксперименты доступны не во всех пространствах и включаются по запросу в поддержку Trisigma. Укажите switchback в allowed_experiment_types. Если участники switchback-эксперимента определяются не по событиям Splitter, задайте у параметра assignments_source_enabled: false. Подробнее - в разделе Switchback.

Если что-то пошло не так

Признак	Причина	Что сделать
`run test`: «В источнике ...v_clickstream_ab_event отсутствуют колонки»	Тип участника объявлен раньше, чем во view появились колонки его параметра	Заведите тип участника в два шага, см. Как завести новый тип участника
«participant_type `<label>` отсутствует в списке допустимых значений»	Тип участника не объявлен, или файл лежит не по пути `traffic_markup/participant_types.yaml`	Проверьте путь файла и label
`run test` проходит, `run merge` завершается ошибкой	Конфликт имён колонок или label с записью из интерфейса	Проверьте ограничения именования и конфликты с интерфейсом
Изменения в метриках перестали применяться после merge	Изменён `type`, `domain` или колонка активного параметра	Верните прежние значения, заведите новый label
Расчёт участников остановился по всем экспериментам	Колонка аллокации равна ключу Splitter при другой колонке связи, или `transform` без `int_id_mapping`	Исправьте конфигурацию по разделам Ограничения именования колонок и Маппинг идентификаторов
Тип участника не появился в форме эксперимента	`status: draft`, нет `participant_types.yaml`, не задан `splitter_allocation_param` или домен типа участника не совпадает с доменом эксперимента	Проверьте статус, файл и поля параметра
Тип участника есть в форме, но в отчёте нет участников	Не заданы `report_allocation_column` или `report_metric_join_column`	У активного параметра колонки не меняются: заведите параметр и тип участника с новым label и всеми тремя именами
Поле не применилось	Опечатка в имени поля	Сверьте имя с таблицей полей

Где находятся файлы​

Контекстный параметр​

Тип участника​

Как завести новый тип участника​

Три имени и путь до отчёта​

Изменения и жизненный цикл​

Что нельзя менять у активного параметра​

Ограничения именования колонок​

Маппинг идентификаторов​

Конфликты с записями из интерфейса​

Типовые сценарии​

Строковый идентификатор участника​

Параметр только для условий отбора​

Тип участника для switchback​

Если что-то пошло не так​