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

Интеграция с Grafana

Источник данных Tuist позволяет использовать в Grafana метрики сборок, тестов и кэша, включая длительности, количество сбоев и сообщаемое время, сэкономленное благодаря кэшированию. Создавайте дашборды вокруг проектов и метрик, важных для вашей команды, или комбинируйте метрики Tuist с другими источниками данных в существующих дашбордах вашей компании. Используйте правила оповещений и каналы уведомлений Grafana, чтобы информировать команду о замедлении сборок или росте числа сбоев.

Доступные метрики#

В таблицах перечислены понятные названия и их идентификаторы для запросов. Запросы состояния сборки используют идентификатор в поле metric; запросы длительности сборок и тестов выбирают average, p50, p90 или p99 в поле series.

Количество сборок и надежность#

Метрика Идентификатор Что измеряет
Количество сборок builds Количество записанных сборок.
Успешные сборки successful_builds Сборки, завершившиеся успешно.
Сбои сборок failed_builds Сборки, завершившиеся с ошибкой.
Отмененные сборки cancelled_builds Сборки, записанные как отмененные. См. различия систем сборки.
Процент успешных сборок success_rate Успешные ÷ (успешные + с ошибками), в процентах.
Сбои или медленные сборки builds_needing_attention Сбои или медленные сборки, учитываются один раз на сборку.

Длительность сборок и тестов#

Метрика Идентификатор Что измеряет
Средняя длительность average Средняя длительность выбранных запусков.
Медианная длительность p50 50-й перцентиль длительности запусков.
Длительность на уровне 90-го процентиля p90 Длительность, ниже или равной которой находятся 90% запусков.
Длительность на уровне 99-го процентиля p99 Длительность, ниже или равной которой находятся 99% запусков.
Порог медленной сборки slow_build_threshold Длительность на уровне 90-го процентиля или ваш фиксированный лимит в миллисекундах.

Метрики длительности тестов используют запуски тестов, записанные в Tuist. Порог медленной сборки применяется только к сборкам: сборка считается медленной, если ее длительность превышает этот порог. Отмененные сборки учитываются отдельно и исключаются из расчета процента успешных сборок.

Экономия кэша#

Метрика Идентификатор Что измеряет
Суммарное сэкономленное время задач (Gradle) cache_work_avoided Сумма оценочного времени выполнения задач, избежанного благодаря попаданиям в кэш.
Сборки, сообщающие суммарное время задач cache_work_avoided_samples Сборки с полной оценкой.
Сообщенная экономия времени кэша cache_time_saved Сумма сообщенной сэкономленной длительности.
Сборки, сообщающие об экономии времени кэша cache_time_saved_samples Сборки с действительным значением экономии.

Плагин Gradle автоматически сообщает оценочное избегание работы для локальных и удаленных попаданий в кэш задач. Для каждой закэшированной задачи он вычитает длительность восстановления задачи из исходного времени выполнения, сохраненного Gradle, с минимумом ноль. Оценка сборки складывает эти значения. Параллельные задачи могут перекрываться, поэтому это суммарное время задач, а не сэкономленная длительность сборки. Актуальные и пропущенные задачи исключаются.

Сборка без попаданий в кэш задач сообщает ноль. Если какой-либо закэшированной задаче не хватает исходных данных о времени, телеметрия неполна или в карте пользовательских метаданных нет места, плагин опускает оценку. Старые версии плагина и другие системы сборки не сообщают ее. Сравните количество отчетов с общим числом сборок, чтобы проверить покрытие.

Сообщенная сэкономленная длительность поступает из метаданных tuist.cache_time_saved_ms. Эта метрика остается отдельной от автоматической оценки.

Экономия кэша не имеет значения, если ни одна сборка не сообщает о ней. Once в настоящее время не записывает это измерение. Попадания и промахи кэша недоступны через этот источник данных.

Таблицы#

Эти идентификаторы являются значениями поля запроса queryType.

Таблица Тип запроса Содержимое
Здоровье по рабочей нагрузке buildWorkloads Количество сборок, процент успешных, медианная длительность и длительность на уровне 90-го процентиля.
Категории сбоев buildFailureReasons Все сбои и их количество по категориям сбоев.
Недавние сбои сборок buildRecentFailures Последние 100 сбоев со ссылками на Tuist.

Недавние сбои включают время начала, длительность, пользователя, ветку и запрошенные задачи. Категории сбоев: verification, infrastructure_tooling и unknown.

Сводки рабочей нагрузки и списки значений веток/рабочих нагрузок возвращают до 1000 значений. Запросы переменных здоровья сборок используют последние 90 дней; устаревшие запросы переменных Gradle сохраняют свое существующее окно истории. Bazel показывает пользователя сборки, сообщаемого инструментом. Другие интеграции показывают учетную запись, связанную с учетными данными для отчетности. Исторические запуски Bazel и Once, а также запуски Once, сообщенные с учетными данными проекта, отображаются как Unknown, если пользователь не был записан.

Используйте фильтр «Категория сбоя» в разделе «Запуски сборок», чтобы найти соответствующие сбои. Категория появляется в деталях сборки с информационной подсказкой, объясняющей ее значение; таблицы обзора по умолчанию и «Запуски сборок» сохраняют свои существующие столбцы. Успешные, отмененные и незавершенные сборки не имеют категории сбоя. Карточка «Аналитика кэша» Gradle и детали сборки показывают «Суммарное сэкономленное время задач»; всплывающая подсказка объясняет оценку и эффект параллельных задач. Виджет кэша сравнивает выбранный диапазон с непосредственно предшествующим периодом той же длины, используя те же фильтры. Сравнения нейтральны: большее общее количество может отражать больше сборок. Отсутствующие предыдущие оценки не показывают сравнение; записанная нулевая базовая линия показывает абсолютное увеличение, а не процент.

Стандартная панель мониторинга#

Импортируйте панель мониторинга здоровья сборок, затем выберите источник данных и проект. Она включает количество сборок, процент успешных, медианную длительность и длительность на уровне 90-го процентиля, порог медленной сборки, нейтральное количество сбоев или медленных сборок, сгруппированную экономию кэша и покрытие отчетностью, а также три таблицы сбоев и рабочих нагрузок. Добавляйте панели для других доступных метрик по мере необходимости. Автоматический порог медленности — это собственный 90-й перцентиль выбранного периода; сборки выше него не обязательно указывают на регрессию. Установите фиксированный порог для оповещений о целевой длительности. Панели кэша приоритизируют автоматическую оценку суммарного времени задач Gradle рядом с ее покрытием, за которой следует явно сообщенная сэкономленная длительность рядом с ее собственным покрытием.

Системы сборки#

Запросы здоровья сборок и стандартная панель мониторинга поддерживают Bazel, Cargo, Once, Gradle и Xcode. Tuist выбирает систему сборки из вашего проекта. Смешанные проекты в настоящее время не поддерживаются запросами здоровья сборок или стандартной панелью мониторинга.

Система сборки Рабочая нагрузка Отчетность об отмене Экономия кэша
Bazel Команда Код выхода 8, кроме run Требует пользовательских метаданных
Cargo Команда Не различается; количество равно нулю Сэкономленная длительность требует пользовательских метаданных; избежание работы компилятора не является сэкономленной длительностью
Once Тип команды Записанная причина отмены Не записывается
Gradle Группа задач Сообщенные отмены Автоматическая оценка избежания работы; сэкономленная длительность требует пользовательских метаданных
Xcode Схема Не различается; количество равно нулю Требует пользовательских метаданных

Обрабатываемые записи и незавершенные запуски исключаются. Bazel включает команды сборки, тестирования, запуска и покрытия кода. Once включает завершенные сборки, тесты и общие запуски. Cargo включает команды сборки, такие как build, check и test-build; устаревшие отчеты о выполнении тестов исключаются из здоровья сборок. Недавние сбои Cargo используют записанное время начала, если оно доступно, иначе переходят на время вставки; отсутствующая длительность остается недоступной, а не равной нулю.

Gradle группирует задачи как инструментальные тесты, модульные тесты, линтинг/проверки, сборка/пакетирование или Другие, в порядке приоритета. Каждая сборка относится к одной рабочей нагрузке. Пользовательские метаданные могут переопределять рабочие нагрузки для Xcode, Bazel, Cargo и Gradle.

Категории сбоев#

Категория Значение Записанные доказательства
verification Код не прошел компиляцию, линковку, тесты или проверки. Исключения верификации или компиляции Gradle и известные типы неудачных задач; проблемы компилятора и линковщика Xcode; структурированные ненулевые результаты действий компилятора/тестов Bazel; записанные неудачные компиляции rustc в Cargo; сбои тестов или неудачные действия в Once, явно объявленные как компиляция, линковка, тест, линтинг или проверка.
infrastructure_tooling Сборка не могла выполняться нормально из-за сбоя инструментов, зависимостей или окружения. Сбои конфигурации, разрешения зависимостей, ввода/вывода или памяти в Gradle; структурированные сбои инфраструктуры Bazel и документированные коды выхода; ошибки действий инфраструктуры в Once.
unknown Отчет не содержит достаточных доказательств для классификации сбоя. Произвольные команды, отсутствующая диагностика и старые отчеты без структурированных доказательств.

Сбои фазы конфигурации Gradle, включая ошибки в скриптах сборки, группируются под инфраструктурой/инструментами, так как выполнение задач не могло продолжаться.

Сбои Cargo без явных метаданных категории или записанной неудачной компиляции rustc остаются unknown; неудачная команда check или test-build сама по себе не устанавливает сбой верификации. Счетчики повторного использования задач Cargo и оцененное избежание работы компилятора никогда не предоставляют ни сэкономленную длительность кэша, ни метрику суммарного времени задач Gradle.

Явные метаданные tuist.failure_category переопределяют автоматическую классификацию. В противном случае доказательства инфраструктуры имеют приоритет над верификацией, когда оба присутствуют в сборке. Неудачный произвольный скрипт не считается сбоем компилятора или теста. Исторические отчеты могут использовать доказательства, которые Tuist уже хранит, но новые поля репортера не заполняют недостающую информацию ретроспективно. Автоматические метаданные репортера используют доступное пространство в рамках существующего лимита из 20 записей пользовательских метаданных.

Ответ buildFailureReasons сохраняет свою строку all для совместимости. Стандартная панель мониторинга фильтрует эту сумму из диаграммы категорий сбоев и показывает общее количество сбоев отдельно. Устаревший запрос gradleFailureReasons сохраняет свои исходные три строки категорий.

Параметры запроса#

Числовые запросы используют следующие значения queryType:

Запрос Тип запроса
Здоровье сборки buildHealth
Длительность сборок Xcode buildDuration
Длительность тестов testDuration

Поле resultMode управляет тем, как возвращаются результаты:

Результат Значение Поведение
Временной ряд series Значение для каждого интервала.
Весь период total Одно значение, рассчитанное по всем запускам в диапазоне.

Метки фильтров соответствуют следующим полям запроса:

Фильтр Поле запроса Доступно для
Среда environment Все запросы
Ветка gitBranch Запросы и таблицы здоровья сборки
Рабочая нагрузка workload Запросы и таблицы здоровья сборки
Статус status Запросы здоровья сборки, таблицы и длительности Xcode
Схема scheme Длительность сборок и тестов Xcode
Конфигурация configuration Длительность сборок Xcode
Тип сборки category Длительность сборок Xcode

Значения среды: any, ci (автоматизированные сборки) и local. Значения статуса: success, failure и, для запросов здоровья сборки, cancelled; опустите значение, чтобы включить все статусы. Значения типа сборки: clean и incremental; опустите значение, чтобы включить оба.

Пустые интервалы здоровья сборки имеют нулевые счетчики и не содержат значений средней длительности, процентиля длительности или коэффициента успешности. Порог медленной сборки по-прежнему использует весь выбранный диапазон. Отдельный запрос длительности тестов возвращает ноль для пустых интервалов временного ряда. Проценты за весь период рассчитываются по запускам, а не по процентилям интервалов. Процентили здоровья сборки используют точную агрегацию; отдельные запросы длительности Xcode и тестов используют приблизительные процентили.

Временные ряды здоровья сборки размещают частичный первый сегмент в начале выбранного диапазона, чтобы он оставался видимым. Устаревшие запросы Gradle сохраняют свои исходные метки времени сегментов.

Все запросы принимают диапазоны дат до 366 дней. Их границы и метки времени различаются:

Запрос Используемая метка времени Границы диапазона
Здоровье сборки: Xcode, Bazel, Cargo, Gradle Время вставки записи Включает начало, исключает конец
Здоровье сборки: Once Время начала запуска Включает начало, исключает конец
Длительность сборок Xcode Время вставки записи Исключает начало и конец
Длительность тестов Записанное время запуска Включает начало и конец

Переменные дашборда#

Используйте переменные дашборда для проектов и поддерживаемых фильтров. Переменные ветки и рабочей нагрузки используют следующие запросы:

Переменная Запрос
Ветка buildBranches account/project
Рабочая нагрузка buildWorkloads account/project

Фильтры принимают одно точное значение. Для переменных ветки и рабочей нагрузки установите пользовательское значение опции «Все» в __tuist_all__. Остальные фильтры используют встроенную опцию «Любой» или пустое значение. Множественный выбор и регулярные выражения не поддерживаются.

Отправка пользовательских метаданных#

Сборки Xcode, Bazel, Cargo и Gradle принимают следующие необязательные значения метаданных:

Ключ Допустимое значение
tuist.workload Название рабочей нагрузки, заменяющее группировку по умолчанию.
tuist.failure_category verification или infrastructure_tooling.
tuist.cache_work_avoided_ms Только Gradle. Автоматически сообщаемая оценка сэкономленной работы в целых миллисекундах, до 365 дней.
tuist.cache_time_saved_ms Целые миллисекунды от 0 до 31 536 000 000 (365 дней).

Передавайте их через конфигурацию пользовательских метаданных вашей интеграции сборки:

json
{
"custom_metadata": {
"values": {
"tuist.workload": "Release verification",
"tuist.failure_category": "verification",
"tuist.cache_time_saved_ms": "12000"
}
}
}

Сообщайте об экономии кэша только при наличии измерения затраченного времени или документально подтвержденной оценки для этой сборки. Одних лишь попаданий в кэш и суммарной длительности задач недостаточно для определения сэкономленного времени при параллельном выполнении задач. Недостающие данные об экономии кэша остаются неизвестными. При отсутствии метаданных категории сбоя система опирается на записанные доказательства, как описано в разделе Системы сборки. Политика хранения данных не меняется.

Оповещения и Slack#

Создайте правило оповещения, управляемое Grafana, с числовой метрикой. Например:

Метрика Идентификатор Пример условия
Коэффициент успешности сборок success_rate Ниже 99%
Неудавшиеся сборки failed_builds Выше нуля
Длительность 90-го процентиля p90 Выше лимита длительности вашей команды

Используйте Весь период для получения одного значения за окно оценки или сведите временной ряд к одному значению. Для запросов длительности в режиме «Весь период» выберите один ряд.

  • Используйте фиксированные значения проекта и фильтров. Переменные дашборда недоступны при фоновой оценке оповещений.
  • Для оповещений используйте числовые запросы. Чтобы отслеживать рабочую нагрузку, отфильтруйте запрос здоровья сборки по этой рабочей нагрузке.
  • Настройте поведение правила при отсутствии данных для интервалов без сборок или сообщенной экономии кэша.

Настройте точку контакта Slack и направьте правило к ней через политику уведомлений Grafana. Grafana отправляет уведомления и хранит учетные данные Slack.

Обновление существующих дашбордов#

Существующие панели длительности сохраняют свои запросы, фильтры, названия рядов и единицы измерения. Сохраненные панели здоровья Gradle и переменные также продолжают работать.

Импортируйте стандартный дашборд отдельно, чтобы использовать общие запросы здоровья сборки. Существующие дашборды не мигрируют автоматически. Общие запросы требуют сервера Tuist, предоставляющего конечные точки здоровья сборки; существующие запросы длительности по-прежнему работают со старыми серверами.

Требования#

  • Grafana 10.4 или новее.
  • Токен Tuist с разрешением на чтение проектов и метрик, которые вы хотите отображать на графиках. См. раздел Аутентификация ниже.

Аутентификация#

Используйте токен аккаунта для дашбордов и фоновой оценки оповещений. Предоставьте project:builds:read для метрик сборок и project:tests:read для длительности тестов, а также ограничьте доступ к проектам, которые вы хотите отображать на графиках. Требуются только те области доступа, которые соответствуют используемым вами метрикам. Следуйте инструкциям по созданию токена, чтобы сгенерировать его.

Интеграция также принимает существующие токены проектов для их собственного проекта и токены доступа пользователя с правами чтения пользователя. Токены доступа пользователя имеют короткий срок действия. Grafana хранит предоставленный вами токен и не обновляет его и не использует ваш локальный вход в Tuist; замените его по истечении срока действия. Токены аккаунта позволяют вам управлять доступом к проектам, разрешениями и сроком действия независимо от сеанса входа пользователя.

Конфигурация#

Добавьте источник данных и настройте:

Поле Сохраненная настройка Примечания
URL сервера jsonData.url По умолчанию https://tuist.dev.
Токен secureJsonData.apiToken Bearer-токен Tuist, хранится в зашифрованном виде.

Выберите Сохранить и проверить, чтобы проверить подключение. Grafana перечисляет доступные проекты, а затем проверяет разрешения на чтение сборок и тестов для первого проекта.

Установка#

Из каталога Grafana#

После публикации установите его как любой другой источник данных через Connections → Add new connection → Tuist или с помощью grafana-cli plugins install tuist-metrics-datasource.

До публикации (самостоятельно размещенная Grafana)#

Плагин не подписан, пока не будет одобрен для каталога. На самостоятельно размещенном экземпляре вы можете:

  • Разрешить неподписанный плагин — добавьте tuist-metrics-datasource в allow_loading_unsigned_plugins (или GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tuist-metrics-datasource) и поместите собранный плагин в вашу директорию плагинов.
  • Подписать его privately для ваших экземпляров — npm run sign -- --rootUrls https://grafana.example.com (URL должен совпадать с root_url экземпляра), затем распространите zip-архив.

Grafana Cloud требует плагины из каталога и не поддерживает неподписанные или вручную загруженные плагины.