コンテンツへスキップ

デバッグ

Tuistは、コマンドが期待通りに動作しない場合に問題を診断するための複数のツールを提供します。

Warning

セッションデータには、ファイルパス、プロジェクト名、リクエスト/レスポンスボディなどの機密情報が含まれる可能性があります。Authorizationなどの機密ヘッダーはマスクされますが、セッションデータを他人と共有する際は注意してください。

セッションデータ#

コマンドの実行が意図した結果をもたらさない場合、セッションデータを検査することで問題を診断できます。CLIはログを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)ファイル

HARファイルの可視化#

HARファイルはセッション中に発生したすべてのHTTPリクエストとレスポンスを記録し、サーバー通信の問題をデバッグするのに役立ちます。HARファイルはいくつかのツールで開くことができます:

  • Proxyman: HTTPトラフィックを表示・分析するためのmacOSネイティブアプリ。ファイル > インポートからHARファイルをインポートします。
  • ブラウザの開発者ツール: Chrome、Firefox、SafariはいずれもネットワークタブでHARファイルのインポートをサポートしています。
  • HAR Viewer: ウェブベースのHARファイルビューアー。
Tip

Tuistのディレクトリ構成とカスタムディレクトリの設定方法については、Directories documentationをご覧ください。

デフォルトでは、CLIは実行が予期せず終了したときにセッションパスを出力します。出力されない場合は、前述のパス(つまり最新のセッションディレクトリ)でセッションデータを見つけることができます。

5日以上経過したセッションディレクトリは自動的にクリーンアップされます。Tuistはデフォルトで最大50個の非アクティブなセッションディレクトリを保持し、現在実行中のTuistプロセスが所有するセッションは保護されます。同じ状態ディレクトリで多くのTuistコマンドを実行するCI環境では、TUIST_SESSION_MAX_SESSIONSを使用して非アクティブセッションの上限を引き上げることができます。例えばTUIST_SESSION_MAX_SESSIONS=200のように設定します。無効な値、ゼロ、負の値は無視され、Tuistはデフォルトの50に戻ります。

継続的インテグレーション#

CIでは環境が使い捨てであるため、TuistセッションデータをエクスポートするようにCIパイプラインを設定したい場合があります。アーティファクトのエクスポートは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キャッシュのデバッグ#

Xcodeキャッシュの問題をデバッグするには、tuist setup cacheの実行時とビルド時の両方でTUIST_CAS_LOGをファイルパスに設定します。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に書き込みます。

ネットワークタイムアウトと再試行の調整#

サーバー呼び出し、レジストリ、プレビュー、キャッシュアーティファクト転送を含むTuistのすべてのHypertext Transfer Protocol (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

リソースタイムアウトは転送全体の壁時計制限であり、ストール検出ではないため、移動する最大のアーティファクトに対応できる十分な大きさが必要です。シャードがダウンロードするテスト製品などのファイル全体転送は、そのため90秒ではなく10分がデフォルトとなり、新しいデータがないままTUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUESTを経過するとストールした転送は依然として失敗します。これらの転送はTUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCEを読み取って上限を引き上げるだけであり、10分未満に下げることはないため、キャッシュリクエストを早く失敗させるために選択した値がシャードのテスト製品ダウンロードをキャンセルすることはありません。TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCEを引き上げると、回復可能だが遅いダウンロードがタイムアウトせずに完了します。キャッシュダウンロードの場合、これはソースからのビルドへのフォールバックではなくキャッシュヒットを得ることを意味するため、意図的に引き上げてください:遅いキャッシュダウンロードを生かすのと同じ値が、ソースからのビルドへのフォールバックを遅延させます。TUIST_HTTP_MAXIMUM_RETRY_COUNTを下げると、長いタイムアウトが複数回の試行で最悪ケースの待ち時間を乗算することを防げます。再試行遅延は各失敗後に倍増し、最大1回分の基本遅延のランダムジッターを含み、30秒を超えることはありません。

カスタムCA証明書の信頼#

デフォルトでは、Tuistはオペレーティングシステムのルートストアに対してTLS証明書を検証します。プライベート認証局を使用するセルフホスト型TuistまたはKuraサーバーを実行する場合、TuistもそのCAを信頼する必要があります。システムキーチェーンにルートをインストールし(SSL用に信頼としてマーク)、これが標準的なアプローチですが、GUIセッションやモバイルデバイス管理(MDM)による信頼ビット設定がないヘッドレスCIホストでは、しばしば実用的ではありません。

そのような場合、Tuistを直接CA証明書バンドルに向けることができます。バンドルはPEM(連結された-----BEGIN CERTIFICATE-----ブロックが1つ以上)または単一のDERファイルにすることができます。システムルートストアはそれ alongside で信頼されたままになるため、公開証明書は通常通り検証され、証明書評価がバイパスされることはありません。

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

また、configuration fileで宣言することもできます:

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

TUIST_CA_CERTIFICATE環境変数は設定ファイルより優先されるため、コミットされたマニフェストを変更せずにCIシークレットとして提供するのが便利です。