Два аналитика по-разному считают метрику "активный пользователь" (один — заходил в приложение, другой — выполнил хотя бы одно целевое действие), из-за чего отчёты не сходятся. Как задокументировать метрику, чтобы избежать таких расхождений в будущем?

Короткий ответ

Нужно завести единое формальное определение метрики в общем каталоге (metric documentation/semantic layer) с точной формулой, источником данных, периодом агрегации, списком исключений (например, тестовые аккаунты) и владельцем, который утверждает любые изменения определения.

Как это работает подробнее

Документация метрики — это не просто текстовое описание «активный пользователь — это...», а воспроизводимая спецификация: точный SQL или формула, таблица-источник, единица агрегации (день/неделя), и явный список того, что исключается из расчёта.

Пример кода

metric-definition.yamlКопировать

metric: active_user
definition: >
  Пользователь считается активным за день, если у него есть
  событие app_open ИЛИ любое из целевых событий (purchase, video_watched)
  в указанную календарную дату (UTC), исключая user_id из списка тестовых аккаунтов.
source: mart.daily_user_activity
owner: Product Analytics Team
last_updated: 2024-05-01

Что использовать на практике

• На практике. Такую документацию полезно хранить рядом с кодом трансформации (например, в dbt как yml-описание модели/метрики) и ссылаться на неё в любом дашборде, который эту метрику показывает, чтобы у читателя не оставалось вопроса «а что конкретно здесь посчитано».
• Проверка. пересчитать метрику по этой формуле обоими аналитиками независимо и убедиться, что цифры сошлись; если нет — ошибка не в определении, а в реализации SQL у одного из них.

Подводные камни

• Частые ошибки. Документируют метрику словами без точной формулы («активный — значит пользовался продуктом»), что оставляет пространство для разных интерпретаций; либо документируют один раз при создании и не актуализируют при изменении логики, из-за чего документация начинает противоречить реальному коду.