# Отладка {#debugging}

Tuist предоставляет несколько инструментов для диагностики проблем, когда команды работают не так, как ожидалось.

> [!WARNING]
> Данные сессии могут содержать конфиденциальную информацию, такую как пути к файлам, названия проектов и тела запросов/ответов. Хотя чувствительные заголовки (например, Authorization) скрываются, будьте осторожны при передаче данных сессии другим лицам.


## Данные сессии {#session-data}

Если вызов команды не дает ожидаемых результатов, вы можете диагностировать проблему, изучив данные сессии. CLI перенаправляет логи в [OSLog](https://developer.apple.com/documentation/os/oslog) и файловую систему.

При каждом запуске создается каталог сессии по пути `$XDG_STATE_HOME/tuist/sessions/{uuid}/`, где `$XDG_STATE_HOME` принимает значение `~/.local/state`, если переменная окружения не установлена. Вы также можете использовать `$TUIST_XDG_STATE_HOME` для установки каталога состояния, специфичного для Tuist, который имеет приоритет над `$XDG_STATE_HOME`.

Каждый каталог сессии содержит:
- **`logs.txt`** — текстовые логи сессии CLI
- **`network.har`** — файл [HTTP Archive (HAR)](https://w3c.github.io/web-performance/specs/HAR/Overview.html), содержащий все сетевые запросы и ответы, сделанные во время сессии

### Просмотр HAR-файлов {#visualizing-har-files}

HAR-файл записывает все HTTP-запросы и ответы, сделанные во время сессии, что полезно для отладки проблем связи с сервером. Вы можете открывать HAR-файлы с помощью нескольких инструментов:

- **[Proxyman](https://proxyman.io/)**: нативное приложение для macOS для просмотра и анализа HTTP-трафика. Импортируйте HAR-файл через File > Import.
- **Инструменты разработчика в браузере**: Chrome, Firefox и Safari поддерживают импорт HAR-файлов на вкладке Network.
- **[HAR Viewer](http://www.softwareishard.com/har/viewer/)**: веб-инструмент для просмотра HAR-файлов.

> [!TIP]
> Узнайте больше об организации каталогов Tuist и о том, как настроить пользовательские каталоги, в <.localized_link href="/cli/directories">документации по каталогам</.localized_link>.


По умолчанию CLI выводит путь к сессии, если выполнение завершается неожиданно. Если этого не происходит, вы можете найти данные сессии по указанному выше пути (то есть в самом последнем каталоге сессии).

Каталоги сессий старше 5 дней автоматически удаляются. По умолчанию Tuist хранит не более 50 неактивных каталогов сессий, сохраняя при этом сессии, принадлежащие текущим запущенным процессам Tuist. В средах CI, где выполняется много команд Tuist с одним и тем же каталогом состояния, вы можете увеличить лимит неактивных сессий с помощью `TUIST_SESSION_MAX_SESSIONS`, например `TUIST_SESSION_MAX_SESSIONS=200`. Недопустимые значения, ноль и отрицательные значения игнорируются, и Tuist возвращается к значению по умолчанию 50.

### Непрерывная интеграция {#diagnose-issues-using-logs-ci}

В среде CI, где окружения являются временными, вы можете настроить свой конвейер CI для экспорта данных сессии Tuist. Экспорт артефактов — это распространенная возможность среди сервисов CI, и конфигурация зависит от используемого сервиса. Например, в GitHub Actions вы можете использовать действие `actions/upload-artifact` для загрузки данных сессии в качестве артефакта:

```yaml
name: Node CI

on: [push]

env:
  TUIST_XDG_STATE_HOME: /tmp

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # ... other steps
      - run: tuist generate
      # ... do something with the project
      - name: Export Tuist session data
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-sessions
          path: /tmp/tuist/sessions/
```

### Отладка кэша Xcode {#cache-daemon-debugging}

Для отладки проблем с кэшем Xcode установите `TUIST_CAS_LOG` в путь к файлу как при выполнении `tuist setup cache`, так и при сборке. Tuist добавляет статистику кэша и ошибки в этот файл:

```bash
export TUIST_CAS_LOG=$HOME/.local/state/tuist/cas.log
tuist setup cache
xcodebuild build -scheme YourScheme
```

В среде CI Tuist записывает этот лог в `~/.local/state/tuist/cas.log` без какой-либо дополнительной настройки.

## Настройка таймаутов сети и повторных попыток {#tuning-network-timeouts}

Весь трафик Tuist по [протоколу передачи гипертекста (HTTP)](https://developer.mozilla.org/en-US/docs/Web/HTTP), включая вызовы сервера, работу с реестром, превью и передачу артефактов кэша, проходит через общий `URLSession` с разумными настройками по умолчанию. На медленных или перегруженных сетевых путях (например, при самостоятельном размещении с доступом к объектному хранилищу через корпоративный прокси) отдельный запрос может исчерпать время ожидания ресурса до завершения. Особенно при загрузке из кэша истечение таймаута заставляет Tuist переключаться на сборку модуля из исходного кода, что намного дороже, чем немного подождать готовый бинарный файл из кэша. Вы можете настроить базовые параметры через переменные окружения; значения по умолчанию применяются, если они не установлены или имеют недопустимое значение:

```bash
# Maximum time (in seconds) a single resource transfer can take before it's cancelled
# (default: 90, or 600 for whole-file transfers such as test-product shard artifacts)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE=600

# Maximum time (in seconds) to wait for new data on an existing request (default: 120)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST=300

# Maximum number of simultaneous connections per host (default: 20)
export TUIST_HTTP_MAXIMUM_CONNECTIONS_PER_HOST=40

# Maximum retries after the initial attempt (default: 3, maximum: 10)
export TUIST_HTTP_MAXIMUM_RETRY_COUNT=1

# Initial exponential backoff delay in milliseconds (default: 100, maximum: 30000)
export TUIST_HTTP_RETRY_BASE_DELAY_IN_MILLISECONDS=250
```

Таймаут ресурса — это ограничение по реальному времени на всю передачу, а не защита от зависания, поэтому он должен быть достаточно большим для самого крупного перемещаемого артефакта. Передачи целых файлов, такие как тестовые продукты, загружаемые шардом, поэтому по умолчанию имеют таймаут 10 минут вместо 90 секунд, а зависшая передача все равно завершается ошибкой после `TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST` при отсутствии новых данных. Эти передачи читают `TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE` только для увеличения своего лимита, никогда не снижая его ниже 10 минут, поэтому значение, выбранное для быстрого отказа запросов к кэшу, не отменяет загрузку тестовых продуктов шардом. Увеличение `TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE` позволяет завершить восстанавливаемую, но медленную загрузку вместо таймаута. Для загрузок из кэша это означает получение попадания в кэш вместо возврата к сборке из исходного кода, поэтому увеличивайте его осознанно: то же значение, которое поддерживает медленную загрузку из кэша, также задерживает возврат к сборке из исходного кода. Снижение `TUIST_HTTP_MAXIMUM_RETRY_COUNT` может предотвратить умножение худшего времени ожидания на несколько попыток при более длительном таймауте. Задержки повторных попыток удваиваются после каждой неудачи, включают до одной базовой задержки случайного джиттера и никогда не превышают 30 секунд.

## Доверие пользовательскому CA-сертификату {#trusting-a-custom-ca-certificate}

По умолчанию Tuist проверяет TLS-сертификаты против корневого хранилища операционной системы. Когда вы запускаете самостоятельно размещенный сервер Tuist или Kura, использующий частный центр сертификации, Tuist также должен доверять этому CA. Установка корневого сертификата в системную связку ключей (и отметка его как доверенного для SSL) является стандартным подходом, но это часто непрактично на headless-хостах CI, где нет графического сеанса или управления мобильными устройствами (MDM) для установки флага доверия.

В таких случаях вы можете напрямую указать Tuist на пакет CA-сертификатов. Пакет может быть в формате PEM (один или несколько объединенных блоков `-----BEGIN CERTIFICATE-----`) или одиночным DER-файлом. Системное корневое хранилище остается доверенным вместе с ним, поэтому публичные сертификаты продолжают проверяться нормально, а оценка сертификатов никогда не обходится.

```bash
# Path to a PEM/DER CA bundle to trust on top of the system root store (default: unset)
export TUIST_CA_CERTIFICATE=/etc/ssl/certs/self-hosted-ca.pem
```

Вы также можете указать его в вашем <.localized_link href="/references/tuist-toml">файле конфигурации</.localized_link>:

```toml
[network]
ca_certificate = "/etc/ssl/certs/self-hosted-ca.pem"
```

Переменная окружения `TUIST_CA_CERTIFICATE` имеет приоритет над файлом конфигурации, что удобно для предоставления в качестве секрета CI без изменения закоммиченного манифеста.