Руководство предназначено для оператора, который проверяет данные проекта перед выпуском или разбирает расхождение на дашборде. Проверьте основу анализа, сравните историю и сохраните параметры представления, чтобы коллега мог повторить проверку. Отдельный шаг настраивает уведомления об изменениях проекта. Телеметрия хостов и сервисов описана в руководстве по мониторингу.
Установите CLI и зависимости по руководству командной строки.
Выполняйте команды в PowerShell из корня исходного репозитория CodeGraph с установленным Python-окружением. Используйте ту же конфигурацию среды исполнения и область проекта, что и API. Замените PROJECT именем зарегистрированного проекта, а USER_ID — идентификатором нужного владельца в локальном хранилище.
1. Проверьте основу анализа проекта
python -m src.cli dashboard health 'PROJECT' --format json
python -m src.cli dashboard basis 'PROJECT' --format json
Ответ связывает проект и ревизию доказательств с основой анализа, доступностью балла и свежестью данных. Состояния stale, missing, failed и unknown помогают выбрать следующий шаг: обновить данные, найти недостающий источник или разобрать причину ошибки. Сохраните состояние и пояснение вместе с результатом проверки.
В ответе health сначала прочитайте health_score_available. При значении true разберите вклады в score_breakdown; при false найдите недостающий источник в health_score_unavailable_reason. Формулы, веса и пример расчёта приведены в методологии оценки.
Если ответ содержит рекомендованную команду обновления, сначала убедитесь, что
refresh_supported = true, а action_availability = available. При
updating наблюдайте текущую задачу и не запускайте дубликат. При failed
сохраните идентификатор задачи и причину ошибки до повтора.
Пример чтения основы анализа
В ответе проекта с текущими данными и без связанного снимка аудита встречается следующая комбинация:
| Поле | Значение в примере | Как прочитать |
|---|---|---|
basis_kind |
live |
Представление использует текущие данные |
coherence_status |
live_only |
Связанный снимок аудита ещё нужен для согласованной основы |
requested_mode |
best_effort |
Команда показывает доступные данные и их состояние |
verdict |
warn |
Прочитайте причину и рекомендованное действие |
cpg_fresh |
false |
Откройте freshness_reason |
freshness_reason |
missing_cpg_commit |
В основе отсутствует commit графа |
В этом примере recommended_action предлагает выполнить свежий отчёт аудита и связать снимки. Сохраните этот ответ, затем проверьте основу повторно после завершения аудита. Значения зависят от данных проекта.
2. Настройте уведомления проекта
Создайте подписку на изменения проекта. Команда сохраняет снимок состояния и передаёт обнаруженные события действующим подпискам проекта. Новая подписка в примере использует локальный inbox: её уведомления доступны владельцу внутри CodeGraph.
python -m src.cli dashboard notifications bootstrap 'PROJECT' --user-id 'USER_ID' --format json
Выберите канал через --channel, способ доставки через --delivery-mode, события через --events и минимальную серьёзность через --minimum-severity. По умолчанию сообщение содержит краткие сведения об изменении. Параметр --include-sensitive-details добавляет чувствительные подробности для каналов, которым разрешён такой доступ.
По умолчанию команда выбирает локальный канал inbox и немедленную доставку.
Этот канал доступен без настройки внешнего получателя. Для отправки через email,
Slack, Telegram или webhook настройте соответствующий канал и укажите его через --channel.
Проверьте в ответе subscription_id, snapshot_id, configured_channels,
dispatched_count и pending. Если состояние проекта не изменилось и новых
событий нет, команда сохраняет снимок и возвращает dispatched_count: 0,
пустой emitted_event_types и пояснение в note.
--no-create-subscription отключает создание подписки, но сохраняет снимок
и передаёт обнаруженные события действующим подпискам. Для проверки доставки
найдите запись успешной доставки в выбранном канале.
Тест канала проверяет доставку сообщения. Одной тестовой отправки недостаточно для проверки реальных уведомлений: измените состояние проекта, запустите bootstrap и сопоставьте тип события и успешную доставку с этим изменением.
3. Проверьте сохранённые представления
python -m src.cli dashboard saved-views list --user-id 'USER_ID' --format json
Перед повторяющимся сравнением или экспортом сохраните идентификатор представления, владельца, область, фильтры и период. Сервис хранит представления в области пользователя; для повторения проверки используйте представление нужного владельца.
Локальный CLI выбирает владельца через --user-id; значение по умолчанию — cli-user. В REST владелец определяется аутентифицированным пользователем, а доступ проверяется API.
Текущие REST-чтения:
GET /api/v1/traceability/saved-views;GET /api/v1/traceability/subscriptions.
Для обоих требуется аутентификация API и подходящая область проекта и пользователя.
4. Сравните историю
Для одного проекта:
python -m src.cli dashboard compare-periods 'PROJECT' --format json
Для автоматизации по портфелю используйте
GET /api/v1/traceability/portfolio/compare-periods с теми же фильтрами,
базовым и сравниваемым периодами, что и в сохранённом представлении. Это
операция чтения. Для CLI периоды по умолчанию: базовый 30d, сравниваемый 7d; задайте их явно через --baseline-period и --comparison-period, если нужны другие интервалы. При недостаточной истории прочитайте пояснение ответа вместо вывода об улучшении или ухудшении. Сохраните селекторы вместе с результатом, чтобы его можно было
воспроизвести.
При недостаточной истории note содержит Not enough snapshot history to compare the selected periods., а diff.metrics пуст. В таком ответе trend_direction может быть stable: это значение по умолчанию пустого сравнения. Для вывода о динамике используйте непустые метрики, идентификаторы снимков и их даты.
5. Соберите данные для диагностики
Зафиксируйте:
- проект и группу;
- текущий коммит или идентификатор развёрнутого образа;
- маршрут или команду с очищенными параметрами;
- состояние и причину свежести;
- идентификатор и этап активной задачи, если они есть;
- сохранённое представление и периоды;
- событие доставки, если инцидент связан с уведомлениями.
Не включайте токены доступа, секреты получателей, сырые приватные замечания и пути хранилища.
Связанные руководства
- Руководство пользователя дашборда — рабочие области, фильтры и действия в интерфейсе.
- Методология оценки — формулы, состав балла и причины недоступности.
- Аудит проекта на основе CPG — получить актуальный отчёт и настроить расписание.
- Мониторинг — метрики сервисов и оповещения об их состоянии.