Настройка метрик

В Trisigma управление метриками происходит через Git-репозиторий. Это позволяет версионировать изменения, проводить ревью кода, гарантировать точность расчетов и использовать единый источник правды для всей компании.

Подготовка к работе

Если вы впервые настраиваете метрики:

Получите доступ к репозиторию конфигураций. Возможны два варианта:

Репозиторий заводит Trisigma на GitHub. Передайте Trisigma электронные адреса, на которые зарегистрированы GitHub-аккаунты участников - команда Trisigma создаёт репозиторий и отправляет приглашения на эти адреса.

Репозиторий вы заводите у себя в GitLab. Разворачиваете его из архива, который передаёт Trisigma. Чтобы бот Trisigma мог читать конфиги и работать с MR, передайте команде Trisigma реквизиты подключения и токен с нужными правами.

Реквизиты подключения:

Параметр	Что это
`host`	адрес вашего GitLab
`project_name`	путь до проекта в GitLab
`repository_name`	последний сегмент пути
`project_id`	числовой ID проекта в GitLab
`default_branch`	основная ветка, в которую сливаются MR. Обычно `main`, но бывает `master` - уточните у админа GitLab
`project_token`	personal access token с правами ниже

Пример:

host: https://gitlab.digital.company.com
project_name: product-analytics/trisigma/ab-test-metrics
repository_name: ab-test-metrics
project_id: 4540
default_branch: main
project_token: <YOUR_PROJECT_TOKEN>

Права токена: доступ к API, чтение и запись репозитория. Конкретно бот использует следующие методы GitLab API:

Что бот делает	Используемые методы
Видит открытые MR	List project merge requests
Забирает конфиги из default-ветки для синка в Trisigma и из MR для валидации	List repository tree, Get file from repository
Читает команды `run test` и `run merge` в комментариях к MR	List MR notes
Публикует в MR сообщения об ошибках в конфигах	Create MR note, Delete MR note, Post comment to commit
Запускает валидацию и сливает MR по команде	Merge a merge request, Get single repository branch, Create a commit with multiple files and actions

Реквизиты и токен получите у коллег, которые администрируют GitLab в вашей компании. Передайте их команде Trisigma в общем чате - она подключит бота к репозиторию.

Склонируйте репозиторий командой git clone. URL репозитория зависит от сценария:
- Если репозиторий на стороне Trisigma - URL придёт в письме с приглашением на GitHub.
- Если репозиторий на вашей стороне - используйте URL из поля url репозитория, который вы указывали при подключении.

Концепция семантического слоя

Семантический слой - это абстракция над сырыми данными в DWH. Вместо того чтобы писать SQL-запрос под каждый отчёт, вы описываете бизнес-логику один раз в связке Source + Metric:

Source - SQL-запрос, который готовит плоскую таблицу с событиями и привязывает их к идентификаторам пользователей.
Metric - правило агрегации (сумма, количество уникальных, соотношение), которое применяют к источнику.

Однажды описанные метрики можно переиспользовать в любых экспериментах без повторного написания кода. Если нужна новая метрика - добавьте новый SQL-источник и опишите формулу в YAML. Существующие метрики при этом не меняются.

Цикл работы с конфигурациями

Необходимые знания

Для шагов ниже нужно базовое знание Git: клонирование репозитория, создание веток, коммиты, пуш и открытие Merge Request в GitLab или GitHub.

Конфигурации метрик лежат в Git-репозитории. Бот Trisigma следит за репозиторием и подхватывает изменения после слияния в основную ветку.

Только через MR

Не коммитьте напрямую в default-ветку и не правьте файлы через веб-UI GitLab/GitHub в обход веток. Бот Trisigma подхватывает изменения только после команд run test и run merge в комментариях к MR. Если обойти этот флоу, правки уйдут в репозиторий, но не доедут до Trisigma - конфигурация в Trisigma и репозиторий разъедутся, а команда Trisigma об этом не узнает.

Цикл одной правки выглядит так:

Клонируем репозиторий. URL приходит в письме с приглашением на GitHub (если репозиторий заводила Trisigma) или указан в данных подключения (если репозиторий у вас в GitLab).

Пишем SQL. Источники лежат в папке sources/sql/. Trisigma ожидает SQL на диалекте Trino (ANSI SQL, совместимый с PostgreSQL). Если вы привыкли писать на ClickHouse SQL, ниже - основные отличия:

Операция	ClickHouse	Trino
Привести к дате	`toDate(col)`	`CAST(col AS date)`
Уникальные значения	`uniq(col)`	`COUNT(DISTINCT col)`
Условный счётчик	`countIf(condition)`	`COUNT(*) FILTER (WHERE condition)`
Проверка на NULL	`isNull(col)`	`col IS NULL`
Текущая дата	`today()`	`current_date`

Подробнее о диалекте: SQL language - Trino Documentation.

Описываем YAML. В sources/sources.yaml регистрируем источник, в metrics/<name>.yaml - формулу метрики.
Запрашиваем валидацию. Открываем Merge Request, в комментарии пишем:
```
run test
```
Бот ставит проверку в очередь и присылает ответ в комментариях к MR. Проверка занимает до 15 минут.
Правим, пока не получим ОК. Если бот вернул ошибки - исправляем, коммитим, пушим, заново пишем run test. Повторяем, пока не придёт сообщение об успешной валидации.
Мерджим после Approve. Просим коллегу поставить Approve - без него бот не сольёт MR. После Approve пишем в комментарии:
```
run merge
```
Бот применяет изменения. В течение 15 минут метрика появляется в интерфейсе Trisigma в разделе Метрики при создании эксперимента.

Если этого не произошло - напишите в поддержку Trisigma, мы проверим причину и поможем доставить метрики.

Добавление новых метрик в будущем

Чтобы добавить новый показатель позже, идите тем же путём: создайте SQL-запрос для новых данных, зарегистрируйте его в sources.yaml и опишите формулу в YAML-файле метрик. Существующие метрики при этом не меняются.

Кейс для примера интеграции (Заведение метрик)

Ниже - описание метрик для кейса с кнопкой. Формулы и SQL-запросы в вашем репозитории будут зависеть от структуры вашего DWH.

На предыдущем шаге Подключение данных Trisigma получила доступ к таблице событий в ClickHouse - той, где хранятся клики по кнопке «Добавить в корзину». Она выглядит так:

user_id	event_type	button_color	timestamp
1001	button_click	blue	2024-03-01 10:02:31
1002	button_click	grey	2024-03-01 10:05:14
1003	button_click	blue	2024-03-01 10:07:45
...	...	...	...

На основе этой таблицы аналитики описывают источник и метрику в Git-репозитории.

Шаг 1. Подготовка источников (Sources)

В папке sources/sql/ создаём файл button_clicks.sql:

-- sources/sql/button_clicks.sql
SELECT user_id, timestamp
FROM dwh.events
WHERE event_type = 'button_click'
AND timestamp BETWEEN :first_date AND :last_date

Это SQL-источник: запрос, который вернёт user_id и время каждого клика по кнопке за период эксперимента. Имя файла button_clicks ссылается из двух мест:

Из sources.yaml, в поле sql: button_clicks - так платформа знает, какой SQL-файл загрузить.
Из metrics.yaml, в поле counter: button_clicks_source - так метрика ссылается на источник.

Путь к таблице

dwh.events в примере - условный путь. Запросы из Trisigma идут через движок Trino, поэтому реальное имя таблицы будет в формате <catalog>.<schema>.<table> и отличается от того, как вы привыкли обращаться к этой таблице напрямую в DWH. Точный путь даст команда Trisigma после настройки коннектора на шаге Подключение данных.

к сведению

Плейсхолдеры :first_date и :last_date

Это обязательные плейсхолдеры. При расчёте эксперимента платформа подставляет в них даты начала и окончания теста. Так СУБД фильтрует данные эффективно, не вычитывая историю за несколько лет.

Именование источников

Используйте snake_case, называйте источник по событию или сущности, которую он описывает (page_views, orders, user_sessions). Избегайте общих названий вроде data или events - когда источников станет много, это усложнит навигацию.

Дальше регистрируем источник в sources/sources.yaml:

# sources/sources.yaml
button_clicks_source:
  # Название SQL-файла в папке sources/sql/
  sql: button_clicks
  # Маппинг: колонка user_id из SQL становится участником типа user_id
  participant: { user_id: user_id }
  # Колонка timestamp используется как дата события для расчётов
  dtm: timestamp
  # Ссылка на файл с формулами метрик
  metric_configs: [button_metrics]

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

Шаг 2. Описание формул (Metrics)

В папке metrics/ создаём файл button_metrics.yaml:

# metrics/button_metrics.yaml
metric.uniq:
  # Количество уникальных пользователей, кликнувших по кнопке
  # users_clicked - название метрики, под которым она появится в интерфейсе Trisigma
  users_clicked:
    # Ссылка на источник из sources.yaml
    counter: button_clicks_source
    # Что именно считаем уникальным (тип участника из sources.yaml)
    key: user_id

metric.uniq - тип агрегации, считающий количество уникальных значений. users_clicked - имя метрики, под которым она появится в интерфейсе Trisigma. counter: button_clicks_source ссылается на источник, зарегистрированный на шаге 1, а key: user_id указывает, что считаем уникальных пользователей.

Имя файла button_metrics ссылается из sources.yaml, где указано metric_configs: [button_metrics].

Шаг 3. Применение изменений

Когда файлы готовы, открываем Merge Request и в комментарии пишем:

run test

Бот ставит проверку в очередь:

Бот ставит Pull Request в очередь на валидацию

Ждём до 15 минут. Если проверка проходит, бот возвращается с подтверждением:

Trisigma-Bot подтверждает успешную валидацию

Если бот вернул ошибки - правим, коммитим, пушим, заново пишем run test. Повторяем, пока не придёт сообщение об успехе.

Просим коллегу-аналитика поставить Approve - важно, чтобы SQL-запросы проверяли коллеги, которые знают данные. После Approve в комментарии пишем:

run merge

Бот применяет изменения. Метрика users_clicked появляется в интерфейсе Trisigma при создании эксперимента.

Следующий шаг - Создание эксперимента.

Подготовка к работе​

Концепция семантического слоя​

Цикл работы с конфигурациями​

Кейс для примера интеграции (Заведение метрик)​

Шаг 1. Подготовка источников (Sources)​

Шаг 2. Описание формул (Metrics)​

Шаг 3. Применение изменений​