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

Руководство пользователя Cat-Scan

Проблема в одной картинке

QPS-воронка

Google отправляет вашему биддеру поток запросов ставок. Каждую секунду десятки тысяч запросов поступают от биржи Authorized Buyers к вашему эндпоинту. Ваш биддер оценивает каждый из них, решает, делать ли ставку, и отвечает -- и все это в течение нескольких миллисекунд.

Вот что упускают большинство людей: подавляющая часть этого сигнала -- шум. Типичное место, получающее 50 000 QPS, может обнаружить, что 30 000 из этих запросов приходят на инвентарь, который медиабайер никогда не собирался покупать: неподходящие географии, нерелевантные домены издателей, размеры объявлений без подходящего креатива. Ваш биддер все равно должен принять, разобрать и отклонить каждый запрос. Это стоит пропускной способности, вычислительных ресурсов и денег.

Диаграмма выше показывает это как дождь. QPS от Google -- это распылитель наверху; капли разлетаются по широкой площади. Ваш биддер -- маленькое ведро внизу. Все, что не попадает в ведро (капли, падающие левее и правее), -- это потери. Вы за них заплатили. Вы ничего не получили взамен.

Cat-Scan существует, чтобы сделать ведро шире, а дождь -- уже.

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

Почему это сложнее, чем кажется

Google Authorized Buyers дает вам всего 10 конфигураций претаргетинга на место, а также грубые географические группы (Восток США, Запад США, Европа, Азия). Reporting API отсутствует. Все данные об эффективности поступают из CSV-экспортов, которые приходят по электронной почте. Сам интерфейс претаргетинга AB функционален, но затрудняет обзор полной картины по конфигам или отмену неудачного изменения.

Cat-Scan закрывает эти пробелы:

  • Он восстанавливает отчетность из CSV-экспортов (ручная загрузка или автоматический импорт из Gmail), дедуплицируя при импорте, чтобы повторная обработка не приводила к двойному подсчету.
  • Он показывает полную RTB-воронку -- от сырого QPS через ставки, победы, показы, клики и расход -- с разбивкой по любому измерению: география, издатель, размер объявления, креатив, конфиг.
  • Он обеспечивает безопасное управление претаргетингом с историей, поэтапными изменениями, предварительным просмотром с пробным прогоном и откатом в один клик.
  • Он запускает оптимизатор, который оценивает сегменты и предлагает изменения конфигов с защитными механизмами воркфлоу (безопасный / сбалансированный / агрессивный), чтобы ни одно изменение не вступило в силу без проверки.

Для кого это руководство

У этого руководства два направления, потому что Cat-Scan обслуживает две совершенно разные роли:

Медиабайеры и менеджеры кампаний используют Cat-Scan для понимания того, куда уходит бюджет, поиска потерь, управления креативами, настройки претаргетинга и одобрения предложений по оптимизации. Они мыслят категориями CPM, процента побед и ROAS. Их главы сосредоточены на том, что показывает интерфейс, что означают цифры и какие действия предпринять.

DevOps и платформенные инженеры используют Cat-Scan для развертывания, мониторинга и устранения неполадок системы. Они мыслят категориями контейнеров, health-эндпоинтов и планов запросов. Их главы сосредоточены на архитектуре, пайплайнах развертывания, операциях с базой данных и руководствах по инцидентам.

Оба направления опираются на общую основу (начало работы, глоссарий), и главы содержат перекрестные ссылки там, где рабочие процессы пересекаются. Медиабайер, сообщающий, что «актуальность данных не работает», и DevOps-инженер, отлаживающий стоящий за этим запрос, должны иметь возможность указать на одну и ту же запись в глоссарии и понять друг друга.

Как читать это руководство

  • Часть 0 для всех. Начните здесь.
  • Часть I -- направление для медиабайера. Если вы работаете с кампаниями, оптимизацией или закупкой, это ваш путь.
  • Часть II -- направление для DevOps. Если вы развертываете, мониторите или администрируете Cat-Scan, это ваш путь.
  • Часть III -- общий справочник: глоссарий, FAQ и указатель API.

Последовательное чтение не требуется. Каждая глава самодостаточна. Следуйте ссылкам, соответствующим вашей роли.

Оглавление

Часть 0: Начало работы

Эту часть читают все.

  • Глава 0: Что такое Cat-Scan? Что делает платформа, для кого она предназначена и основные концепции, которые нужно знать в первую очередь: места, QPS, претаргетинг, RTB-воронка.

  • Глава 1: Вход в систему Способы аутентификации (Google OAuth, локальные аккаунты), страница входа, что делать при неудачном входе и как работает выбор места.

  • Глава 2: Навигация по панели управления Боковая панель, переключение между местами, выбор языка, чек-лист настройки для новых аккаунтов и организация страниц.

Часть I: Направление для медиабайера

Для медиабайеров, менеджеров кампаний и инженеров по оптимизации.

  • Глава 3: Как читать QPS-воронку Главная страница. Как читать разбивку воронки: показы, ставки, победы, расход, процент побед, CTR, CPM. Что такое «потери» в конкретных терминах. Карточки конфигов и что контролируют их поля.

  • Глава 4: Анализ потерь по измерениям Три представления анализа потерь и когда использовать каждое:

  • Географическое (/qps/geo): какие страны и города расходуют QPS без конверсий.
  • По издателям (/qps/publisher): какие домены и приложения показывают низкую эффективность.

  • По размерам (/qps/size): какие размеры объявлений получают трафик, но не имеют подходящих креативов. Google отправляет ~400 различных размеров; большинство нерелевантны для медийной рекламы фиксированного размера.

  • Глава 5: Управление креативами Галерея креативов (/creatives): просмотр по формату, фильтрация по уровню эффективности, поиск по ID. Миниатюры, значки форматов, диагностика целевых URL. Кластеризация по кампаниям (/campaigns): перетаскивание, AI-автокластеризация, пул неназначенных.

  • Глава 6: Настройка претаргетинга Что контролирует конфиг претаргетинга (географии, размеры, форматы, платформы, максимальный QPS). Как читать карточку конфига. Применение изменений с пробным прогоном. Хронология истории изменений (/history). Откат: как работает, зачем нужен и когда использовать.

  • Глава 7: Оптимизатор (BYOM) Bring Your Own Model: регистрация внешнего эндпоинта оценки, его валидация, активация. Жизненный цикл «оценка -- предложение -- одобрение -- применение». Пресеты воркфлоу: безопасный, сбалансированный, агрессивный. Экономика: эффективный CPM, базовая стоимость хостинга, сводка эффективности. Как выглядит предложение и как его оценить.

  • Глава 8: Конверсии и атрибуция Подключение источника конверсий. Интеграция пикселя. Настройка вебхука: HMAC- подписи, общие секреты, ограничение частоты. Проверки готовности. Статистика приема. Что означает «здоровье конверсий» и как читать страницу статуса безопасности.

  • Глава 9: Импорт данных Как данные попадают в Cat-Scan и почему это важно. Ручная загрузка CSV (/import): перетаскивание, маппинг столбцов, валидация, поблочная загрузка для больших файлов. Автоимпорт через Gmail: как работает, как проверить статус, что происходит при сбое. Таблица актуальности данных: что означает «импортировано» и «отсутствует» для каждой даты и типа отчета. Гарантии дедупликации.

  • Глава 10: Как читать отчеты Статистика расходов, панели эффективности конфигов, метрики эффективности эндпоинтов. Как интерпретировать тренды. Что показывает ежедневная разбивка. Сравнение снимков: до и после изменения претаргетинга.

Часть II: Направление для DevOps

Для платформенных инженеров, SRE и системных администраторов.

  • Глава 11: Обзор архитектуры Топология системы: бэкенд на FastAPI, фронтенд на Next.js 14, Postgres (Cloud SQL), BigQuery. Почему используются обе базы данных (стоимость, латентность, преагрегация, управление соединениями). Компоновка контейнеров: api, dashboard, oauth2-proxy, cloudsql-proxy, nginx. Цепочка доверия аутентификации: OAuth2 Proxy устанавливает X-Email, nginx передает его, API доверяет ему.

  • Глава 12: Развертывание CI/CD-пайплайн: GitHub Actions build-and-push.yml собирает образы при пуше; deploy.yml запускается только вручную (с подтверждением DEPLOY). Теги образов в Artifact Registry (sha-XXXXXXX). Последовательность развертывания: git pull на ВМ, docker compose pull, пересоздание, очистка. Верификация после развертывания: проверка здоровья, проверка контрактов. Почему автоматическое развертывание отключено (инцидент в январе 2026). Как проверить развертывание: curl /api/health | jq .git_sha.

  • Глава 13: Мониторинг здоровья и диагностика Health-эндпоинты: /api/health (проверка жизнеспособности), /system/data-health (полнота данных). Страница состояния системы (/settings/system): Python, Node, FFmpeg, база данных, диск, миниатюры. Скрипты проверки среды выполнения: diagnose_v1_buyer_report_coverage.sh, run_v1_runtime_health_strict_dispatch.sh. Канареечная аутентификация: CATSCAN_CANARY_EMAIL, CATSCAN_BEARER_TOKEN. CI-воркфлоу: v1-runtime-health-strict.yml и значения PASS/FAIL/BLOCKED.

  • Глава 14: Операции с базой данных Только Postgres в продакшене. Cloud SQL через прокси-контейнер. Ключевые таблицы и их масштаб: rtb_daily (~84M строк), rtb_bidstream (~21M строк), rtb_quality, rtb_bid_filtering. Критические индексы: (buyer_account_id, metric_date DESC). Модель соединений: по запросу (без пула), run_in_executor для асинхронности. Таймауты запросов (SET LOCAL statement_timeout). Настройки хранения данных. Роль BigQuery: пакетное хранилище сырых данных; Postgres предоставляет приложению преагрегированные данные.

  • Глава 15: Руководство по устранению неполадок Известные паттерны сбоев и способы их устранения:

  • Цикл авторизации: Cloud SQL Proxy не работает, _get_or_create_oauth2_user молча падает, /auth/check возвращает {authenticated:false}, фронтенд зацикливается на редиректах. Трехуровневое исправление. Как обнаружить: счетчик редиректов в браузере, 503 от /auth/check.
  • Таймаут data-freshness: Большие таблицы выполняют последовательное сканирование вместо использования индексов. Симптомы: /uploads/data-freshness завершается по таймауту или возвращает 500. Диагностика: pg_stat_activity, EXPLAIN ANALYZE. Паттерн исправления: generate_series + EXISTS.
  • Сбой импорта из Gmail: /gmail/status показывает ошибку. Проверьте контейнер Cloud SQL Proxy. Проверьте количество непрочитанных.

  • Порядок перезапуска контейнеров: cloudsql-proxy должен быть работоспособен до запуска api. Признаки неправильного порядка: connection refused в логах API.

  • Глава 16: Управление пользователями и правами Панель администратора (/admin): создание пользователей (локальных и предварительное создание OAuth), управление ролями, права по местам. Сервисные аккаунты: загрузка JSON учетных данных GCP, что это открывает (обнаружение мест, синхронизация претаргетинга). Пользователи с ограниченным доступом: что они видят и что скрыто. Журнал аудита: какие действия отслеживаются, как фильтровать, период хранения.

  • Глава 17: Интеграции Сервисные аккаунты GCP и подключение проекта. Google Authorized Buyers API: обнаружение мест, синхронизация конфигов претаргетинга, синхронизация RTB- эндпоинтов. Интеграция с Gmail: OAuth2 для автоматического приема отчетов. Провайдеры языкового AI: Gemini, Claude, Grok (для определения языка креативов и оповещений о несоответствиях). Вебхуки конверсий: регистрация эндпоинтов, HMAC-верификация, ограничение частоты, мониторинг актуальности.

Часть III: Справочник

Общий для обоих направлений.

  • Глоссарий Каждый термин на двух языках. Колонка медиабайера: «претаргетинг» -- это «правила, определяющие, какие запросы ставок достигают вашего биддера». Колонка DevOps: «претаргетинг» -- это «изменяемая сущность, синхронизируемая из AB API, хранящаяся в pretargeting_configs, доступная через /settings/pretargeting». Обоим нужно одно и то же слово; никто не использует определение другого.

  • Часто задаваемые вопросы С тегами по ролям. Вопросы медиабайера («Почему мое покрытие 74%?») рядом с вопросами DevOps-инженера («Почему проверка runtime health strict gate не прошла?»). Ответы содержат ссылки на соответствующие главы.

  • Краткий справочник по API Все 118+ эндпоинтов, сгруппированных по доменам: ядро, места, креативы, кампании, аналитика, настройки, администрирование, оптимизатор, конверсии, интеграции, загрузки, снимки, авторизация. Метод, путь, ключевые параметры и что возвращает. Не замена спецификации OpenAPI по адресу /api/docs, но навигационный указатель.