Телеметрия
Tuist предоставляет три взаимодополняющих сигнала наблюдаемости: метрики (Prometheus), трейсы (OpenTelemetry) и логи (совместимые с Loki). Все три опциональны и могут включаться независимо.
Распределённая трассировка (OpenTelemetry)#
Tuist поддерживает OpenTelemetry для распределённой трассировки. При включении сервер генерирует трейсы для HTTP-запросов (Phoenix и Bandit), запросов к базе данных (Ecto), исходящих HTTP-вызовов (Finch) и обработки сообщений Broadway. Эти трейсы помогают понять задержки запросов, выявить медленные запросы и отслеживать запросы между сервисами.
Конфигурация#
Установите следующую переменную окружения, чтобы включить экспорт трейсов:
| Переменная окружения | Описание | Обязательно | По умолчанию | Пример |
|---|---|---|---|---|
TUIST_OTEL_EXPORTER_OTLP_ENDPOINT | gRPC-эндпоинт OpenTelemetry Collector (например, Grafana Alloy, Jaeger или любой коллектор, совместимый с OTLP) | Нет | http://localhost:4317 |
Если эта переменная не установлена, трассировка отключена и не добавляет накладных расходов.
Инструментированные библиотеки#
Следующие библиотеки автоматически инструментируются при включении трассировки:
- Bandit — спаны соединений HTTP-сервера
- Phoenix — спаны жизненного цикла запроса (действия контроллеров, LiveView)
- Ecto — спаны запросов к базе данных с метаданными запроса
- Finch — спаны исходящих HTTP-запросов клиента
- Broadway — спаны конвейера обработки сообщений
Пример настройки с Grafana Alloy#
Если вы используете Grafana Alloy в качестве коллектора, настройте его на приём OTLP-трейсов и пересылку в ваш бэкенд трассировки (например, Grafana Cloud Tempo):
otelcol.receiver.otlp "default" {
grpc {
endpoint = "0.0.0.0:4317"
}
output {
traces = [otelcol.exporter.otlp.your_backend.input]
}
}
Затем установите TUIST_OTEL_EXPORTER_OTLP_ENDPOINT, указав на экземпляр Alloy, например http://alloy:4317.
Пересылка логов (Loki)#
Tuist может пересылать логи приложения на эндпоинт, совместимый с Loki. Это позволяет централизовать логи вместе с метриками и трейсами для полной картины наблюдаемости. Логи отправляются через HTTP push API Loki (/loki/api/v1/push) и включают метки для app, env и level.
Конфигурация#
| Переменная окружения | Описание | Обязательно | По умолчанию | Пример |
|---|---|---|---|---|
TUIST_LOKI_URL | Базовый URL эндпоинта push API, совместимого с Loki | Нет | http://localhost:3100 |
Если эта переменная не установлена, пересылка логов отключена.
Пример настройки с Grafana Alloy#
Grafana Alloy может выступать в роли локального ретранслятора логов, используя компонент loki.source.api:
loki.source.api "default" {
http {
listen_address = "0.0.0.0"
listen_port = 3100
}
forward_to = [loki.write.your_backend.receiver]
use_incoming_timestamp = true
}
loki.write "your_backend" {
endpoint {
url = "https://your-loki-instance/loki/api/v1/push"
basic_auth {
username = "your-username"
password = "your-password"
}
}
}
Затем установите TUIST_LOKI_URL=http://alloy:3100.
Вы также можете направить TUIST_LOKI_URL напрямую на экземпляр Loki, если он предоставляет push API.
Метрики Prometheus#
Вы можете собирать метрики, полученные сервером Tuist, с помощью Prometheus и инструмента визуализации, такого как Grafana, чтобы создать собственную панель управления под ваши нужды. Метрики Prometheus доступны через эндпоинт /metrics на порту 9091. Параметр scrape_interval в Prometheus следует установить меньше 10_000 секунд (мы рекомендуем 30 секунд, чтобы соблюсти баланс между наблюдаемостью и затратами на сбор метрик).
Мониторинг реальных пользователей#
Tuist может сообщать о производительности браузера на маркетинговом сайте, в документации и на панели управления, используя веб-SDK Grafana Faro, который встроен в отдаваемый JavaScript. Он фиксирует основные веб-метрики (включая Largest Contentful Paint), необработанные ошибки и просмотры страниц и отправляет их в запущенный вами Faro receiver — например, компонент faro.receiver в Grafana Alloy, который пересылает данные в Loki и Tempo.
Конфигурация#
| Переменная окружения | Описание | Обязательно | По умолчанию | Пример |
|---|---|---|---|---|
TUIST_FARO_COLLECTOR_URL | URL, на который браузер отправляет полезные нагрузки Faro | Нет | /-/faro |
Мониторинг реальных пользователей включается только при установке TUIST_FARO_COLLECTOR_URL. Без него телеметрия браузера не собирается и сторонние скрипты не загружаются.
Путь того же источника, например /-/faro, позволяет избежать кросс-доменных запросов и не меняет политику безопасности контента (CSP) браузера. Направьте его на ваш Faro receiver через ingress.
Что собирается#
- Веб-метрики: LCP, CLS, INP, FCP и TTFB, автоматически фиксируемые браузером
- Просмотры страниц: фиксируются при загрузке и при навигации через Phoenix LiveView
- Разделы: каждая полезная нагрузка содержит раздел, из которого она поступила —
marketing,docs,dashboardилиapi-docs - Ошибки: необработанные исключения и необработанные отклонения промисов
Вопросы конфиденциальности#
- Идентификатор пользователя не привязывается: полезные нагрузки не содержат ID пользователя, email или учётной записи
- Сессии не сохраняются между визитами, поэтому в хранилище браузера ничего не записывается
- Захват консоли отключён, поэтому вывод логов приложения никогда не отправляется из браузера
Метрики Elixir#
По умолчанию мы включаем метрики среды выполнения Elixir, BEAM, Elixir и некоторых используемых библиотек. Вот некоторые из доступных метрик:
Рекомендуем ознакомиться с этими страницами, чтобы узнать, какие метрики доступны и как их использовать.
Метрики запусков#
Набор метрик, связанных с запусками Tuist.
tuist_runs_total (счётчик)#
Общее количество запусков Tuist.
Теги#
| Тег | Описание |
|---|---|
name | Название выполненной команды tuist, например build, test и т. д. |
is_ci | Логическое значение, указывающее, был ли исполнителем CI или машина разработчика. |
status | 0 при success, 1 при failure. |
tuist_runs_duration_milliseconds (гистограмма)#
Общая длительность каждого запуска tuist в миллисекундах.
Теги#
| Тег | Описание |
|---|---|
name | Название выполненной команды tuist, например build, test и т. д. |
is_ci | Логическое значение, указывающее, был ли исполнителем CI или машина разработчика. |
status | 0 при success, 1 при failure. |
Метрики кэша#
Набор метрик, связанных с кэшем Tuist.
tuist_cache_events_total (счётчик)#
Общее количество событий бинарного кэша.
Теги#
| Тег | Описание |
|---|---|
event_type | Может быть local_hit, remote_hit или miss. |
tuist_cache_uploads_total (счётчик)#
Количество загрузок в бинарный кэш.
tuist_cache_uploaded_bytes (сумма)#
Количество байт, загруженных в бинарный кэш.
tuist_cache_downloads_total (счётчик)#
Количество скачиваний из бинарного кэша.
tuist_cache_downloaded_bytes (сумма)#
Количество байт, скачанных из бинарного кэша.
Метрики превью#
Набор метрик, связанных с функцией превью.
tuist_previews_uploads_total (сумма)#
Общее количество загруженных превью.
tuist_previews_downloads_total (сумма)#
Общее количество скачанных превью.
Метрики хранилища#
Набор метрик, связанных с хранением артефактов в удалённом хранилище (например, S3).
Эти метрики полезны для понимания производительности операций хранилища и выявления потенциальных узких мест.
tuist_storage_get_object_size_size_bytes (гистограмма)#
Размер объекта (в байтах), полученного из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_get_object_size_duration_miliseconds (гистограмма)#
Длительность (в миллисекундах) получения размера объекта из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_get_object_size_count (счётчик)#
Количество раз, когда размер объекта был получен из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_delete_all_objects_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) удаления всех объектов из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
project_slug | Слаг проекта, объекты которого удаляются. |
tuist_storage_delete_all_objects_count (счётчик)#
Количество раз, когда все объекты проекта были удалены из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
project_slug | Слаг проекта, объекты которого удаляются. |
tuist_storage_multipart_start_upload_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) начала загрузки в удалённое хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_multipart_start_upload_duration_count (счётчик)#
Количество раз, когда загрузка в удалённое хранилище была начата.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_get_object_as_string_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) получения объекта в виде строки из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_get_object_as_string_count (счётчик)#
Количество раз, когда объект был получен в виде строки из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_check_object_existence_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) проверки существования объекта в удалённом хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_check_object_existence_count (счётчик)#
Количество раз, когда проверялось существование объекта в удалённом хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_generate_download_presigned_url_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) генерации предварительно подписанного URL для скачивания объекта из удалённого хранилища.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_generate_download_presigned_url_count (счётчик)#
Количество раз, когда для объекта в удалённом хранилище генерировался предварительно подписанный URL для скачивания.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
tuist_storage_multipart_generate_upload_part_presigned_url_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) генерации предварительно подписанного URL для загрузки части объекта в удалённое хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
part_number | Номер части загружаемого объекта. |
upload_id | Идентификатор многокомпонентной загрузки. |
tuist_storage_multipart_generate_upload_part_presigned_url_count (счётчик)#
Количество раз, когда для объекта в удалённом хранилище генерировался предварительно подписанный URL для загрузки части.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
part_number | Номер части загружаемого объекта. |
upload_id | Идентификатор многокомпонентной загрузки. |
tuist_storage_multipart_complete_upload_duration_milliseconds (гистограмма)#
Длительность (в миллисекундах) завершения загрузки в удалённое хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
upload_id | Идентификатор многокомпонентной загрузки. |
tuist_storage_multipart_complete_upload_count (счётчик)#
Общее количество завершённых загрузок в удалённое хранилище.
Теги#
| Тег | Описание |
|---|---|
object_key | Ключ поиска объекта в удалённом хранилище. |
upload_id | Идентификатор многокомпонентной загрузки. |
Метрики аутентификации#
Набор метрик, связанных с аутентификацией.
tuist_authentication_token_refresh_error_total (счётчик)#
Общее количество ошибок обновления токена.
Теги#
| Тег | Описание |
|---|---|
cli_version | Версия Tuist CLI, в которой произошла ошибка. |
reason | Причина ошибки обновления токена, например invalid_token_type или invalid_token. |
Метрики проектов#
Набор метрик, связанных с проектами.
tuist_projects_total (последнее значение)#
Общее количество проектов.
Метрики аккаунтов#
Набор метрик, связанных с аккаунтами (пользователями и организациями).
tuist_accounts_organizations_total (последнее значение)#
Общее количество организаций.
tuist_accounts_users_total (последнее значение)#
Общее количество пользователей.
Метрики базы данных#
Набор метрик, связанных с подключением к базе данных.
Метрики пула репозиториев собираются внутри системы каждые 100 мс, а затем передаются в Prometheus по адресу /metrics. Метрики last_value ниже показывают последнее состояние пула на момент сбора. Метрики нагрузки далее представляют собой суммы, полученные из этих 100-миллисекундных выборок, что позволяет легче обнаруживать короткие периоды насыщения, даже если они завершаются до следующего сбора.
tuist_repo_pool_checkout_queue_length (последнее значение)#
Количество запросов к базе данных, находящихся в очереди и ожидающих назначения соединения.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_ready_conn_count (последнее значение)#
Количество соединений с базой данных, готовых к выполнению запроса.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_size (последнее значение)#
Настроенное количество соединений в пуле.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_checkout_queue_total_samples_sum (сумма)#
Общее количество опросов пула репозиториев (увеличивается на 1 при каждом опросе). Используйте это значение как знаменатель при вычислении процентов занятости или голодания: rate(busy_samples) / rate(total_samples) или rate(starved_samples) / rate(total_samples).
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_checkout_queue_observed_sum (сумма)#
Сумма поставленных в очередь запросов на получение соединения, наблюдаемых во время опросов пула репозиториев. Это полезно для обнаружения коротких всплесков конкуренции за ресурсы пула, которые могут быть не видны только по последнему образцу длины очереди.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_checkout_queue_busy_samples_sum (сумма)#
Количество опросов пула репозиториев, при которых хотя бы один запрос на получение соединения из базы данных ожидал в очереди.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_checkout_queue_starved_samples_sum (сумма)#
Количество опросов пула репозиториев, при которых запросы на получение соединения были поставлены в очередь, но не было доступных готовых соединений. Устойчивый рост этого показателя обычно означает насыщение пула.
Теги#
| Тег | Описание |
|---|---|
repo | Репозиторий, отправивший метрику, например postgres, clickhouse_read или clickhouse_write. |
database | Тип используемой базы данных, например postgres или clickhouse. |
tuist_repo_pool_db_connection_connected (счетчик)#
Количество установленных соединений с базой данных.
tuist_repo_pool_db_connection_disconnected (счетчик)#
Количество отключенных от базы данных соединений.
Теги#
| Тег | Описание |
|---|---|
tag | Тег слушателя DBConnection, идентифицирующий репозиторий-источник. |
Метрики HTTP#
Набор метрик, связанных с взаимодействием Tuist с другими сервисами по HTTP.
tuist_http_request_count (счетчик)#
Количество исходящих HTTP-запросов.
tuist_http_request_duration_nanosecond_sum (сумма)#
Суммарная длительность исходящих запросов (включая время ожидания назначения соединения).
tuist_http_request_duration_nanosecond_bucket (распределение)#
Распределение длительности исходящих запросов (включая время ожидания назначения соединения).
tuist_http_queue_count (счетчик)#
Количество запросов, полученных из пула.
tuist_http_queue_duration_nanoseconds_sum (сумма)#
Время, необходимое для получения соединения из пула.
tuist_http_queue_idle_time_nanoseconds_sum (сумма)#
Время простоя соединения в ожидании получения.
tuist_http_queue_duration_nanoseconds_bucket (распределение)#
Время, необходимое для получения соединения из пула.
tuist_http_queue_idle_time_nanoseconds_bucket (распределение)#
Время простоя соединения в ожидании получения.
tuist_http_connection_count (счетчик)#
Количество установленных соединений.
tuist_http_connection_duration_nanoseconds_sum (сумма)#
Время, необходимое для установления соединения с хостом.
tuist_http_connection_duration_nanoseconds_bucket (распределение)#
Распределение времени, необходимого для установления соединения с хостом.
tuist_http_send_count (счетчик)#
Количество запросов, отправленных после назначения им соединения из пула.
tuist_http_send_duration_nanoseconds_sum (сумма)#
Время, необходимое для завершения запросов после назначения им соединения из пула.
tuist_http_send_duration_nanoseconds_bucket (распределение)#
Распределение времени, необходимого для завершения запросов после назначения им соединения из пула.
tuist_http_receive_count (счетчик)#
Количество ответов, полученных на отправленные запросы.
tuist_http_receive_duration_nanoseconds_sum (сумма)#
Время, затраченное на получение ответов.
tuist_http_receive_duration_nanoseconds_bucket (распределение)#
Распределение времени, затраченного на получение ответов.
tuist_http_queue_available_connections (последнее значение)#
Количество доступных соединений в очереди.
tuist_http_queue_in_use_connections (последнее значение)#
Количество используемых соединений в очереди.