# Интеграция с Grafana {#grafana}

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

## Доступные метрики {#metric-definitions}

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

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

| Метрика | Идентификатор | Что измеряет |
| --- | --- | --- |
| Количество сборок | `builds` | Количество записанных сборок. |
| Успешные сборки | `successful_builds` | Сборки, завершившиеся успешно. |
| Сбои сборок | `failed_builds` | Сборки, завершившиеся с ошибкой. |
| Отмененные сборки | `cancelled_builds` | Сборки, записанные как отмененные. См. [различия систем сборки](#build-systems). |
| Процент успешных сборок | `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 и детали сборки показывают «Суммарное сэкономленное время задач»; всплывающая подсказка объясняет оценку и эффект параллельных задач. Виджет кэша сравнивает выбранный диапазон с непосредственно предшествующим периодом той же длины, используя те же фильтры. Сравнения нейтральны: большее общее количество может отражать больше сборок. Отсутствующие предыдущие оценки не показывают сравнение; записанная нулевая базовая линия показывает абсолютное увеличение, а не процент.

## Стандартная панель мониторинга {#what-you-can-query}

Импортируйте [панель мониторинга здоровья сборок](https://github.com/tuist/tuist/blob/main/grafana-datasource/src/dashboards/build-health.json), затем выберите источник данных и проект. Она включает количество сборок, процент успешных, медианную длительность и длительность на уровне 90-го процентиля, порог медленной сборки, нейтральное количество сбоев или медленных сборок, сгруппированную экономию кэша и покрытие отчетностью, а также три таблицы сбоев и рабочих нагрузок. Добавляйте панели для других доступных метрик по мере необходимости. Автоматический порог медленности — это собственный 90-й перцентиль выбранного периода; сборки выше него не обязательно указывают на регрессию. Установите фиксированный порог для оповещений о целевой длительности. Панели кэша приоритизируют автоматическую оценку суммарного времени задач Gradle рядом с ее покрытием, за которой следует явно сообщенная сэкономленная длительность рядом с ее собственным покрытием.

## Системы сборки {#build-systems}

Запросы здоровья сборок и стандартная панель мониторинга поддерживают 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 и [документированные коды выхода](https://bazel.build/run/scripts); ошибки действий инфраструктуры в Once. |
| `unknown` | Отчет не содержит достаточных доказательств для классификации сбоя. | Произвольные команды, отсутствующая диагностика и старые отчеты без структурированных доказательств. |

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

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

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

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

## Параметры запроса {#query-options}

Числовые запросы используют следующие значения `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__`. Остальные фильтры используют встроенную опцию «Любой» или пустое значение. Множественный выбор и регулярные выражения не поддерживаются.

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

Сборки 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"
    }
  }
}
```

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

## Оповещения и Slack {#alerts-and-slack}

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

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

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

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

Настройте [точку контакта Slack](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-slack/) и направьте правило к ней через политику уведомлений Grafana. Grafana отправляет уведомления и хранит учетные данные Slack.

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

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

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

## Требования {#requirements}

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

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

Используйте <.localized_link href="/guides/server/authentication#account-tokens">токен аккаунта</.localized_link> для дашбордов и фоновой оценки оповещений. Предоставьте `project:builds:read` для метрик сборок и `project:tests:read` для длительности тестов, а также ограничьте доступ к проектам, которые вы хотите отображать на графиках. Требуются только те области доступа, которые соответствуют используемым вами метрикам. Следуйте <.localized_link href="/guides/server/authentication#creating-an-account-token">инструкциям по созданию токена</.localized_link>, чтобы сгенерировать его.

Интеграция также принимает существующие токены проектов для их собственного проекта и <.localized_link href="/guides/server/authentication#as-a-user">токены доступа пользователя</.localized_link> с правами чтения пользователя. Токены доступа пользователя имеют короткий срок действия. Grafana хранит предоставленный вами токен и не обновляет его и не использует ваш локальный вход в Tuist; замените его по истечении срока действия. Токены аккаунта позволяют вам управлять доступом к проектам, разрешениями и сроком действия независимо от сеанса входа пользователя.

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

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

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

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

## Установка {#installation}

### Из каталога Grafana {#from-the-grafana-catalog}

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

### До публикации (самостоятельно размещенная Grafana) {#before-it-is-published-self-hosted-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 требует плагины из каталога](https://grafana.com/docs/grafana-cloud/learn-and-build/get-started/learn/find-and-use-plugins/) и не поддерживает неподписанные или вручную загруженные плагины.
